d4d82b8f54c489a4d38b30f62d7835772478d7df
1 package HTML
::Element
::Library
;
5 our $VERSION = '5.120100';
8 use Array
::Group
':all';
11 use Data
::Rmap
'rmap_array';
14 use List
::MoreUtils
':all';
15 use List
::Rotation
::Cycle
;
16 use List
::Util
'first';
17 use Params
::Validate
':all';
20 # https://rt.cpan.org/Ticket/Display.html?id=44105
21 sub HTML
::Element
::fillinform
{
22 my ($tree, $hashref, $return_tree, $guts) = @_;
23 (ref $hashref) eq 'HASH' or confess
'hashref not supplied as argument' ;
25 my $html = $tree->as_HTML;
26 my $new_html = HTML
::FillInForm
->fill(\
$html, $hashref);
29 $tree = HTML
::TreeBuilder
->new_from_content($new_html);
30 $tree = $guts ?
$tree->guts : $tree ;
36 sub HTML
::Element
::siblings
{
38 my $p = $element->parent;
43 sub HTML
::Element
::defmap
{
44 my($tree, $attr, $hashref, $debug) = @_;
46 while (my ($k, $v) = (each %$hashref)) {
47 warn "defmap looks for ($attr => $k)" if $debug;
48 my $found = $tree->look_down($attr => $k);
50 warn "($attr => $k) was found.. replacing with '$v'" if $debug;
51 $found->replace_content( $v );
56 sub HTML
::Element
::_only_empty_content
{
58 my @c = $self->content_list;
59 my $length = scalar @c;
61 scalar @c == 1 and not length $c[0];
64 sub HTML
::Element
::prune
{
67 for my $c ($self->content_list) {
73 $self->delete if ($self->is_empty or $self->_only_empty_content);
77 sub HTML
::Element
::newchild
{
78 my ($lol, $parent_label, @newchild) = @_;
80 if ($_->[0] eq $parent_label) {
81 $_ = [ $parent_label => @newchild ];
89 sub HTML
::Element
::crunch
{ ## no critic (RequireArgUnpacking)
90 my $container = shift;
92 my %p = validate
(@_, {
93 look_down
=> { type
=> ARRAYREF
},
94 leave
=> { default => 1 },
97 my @look_down = @
{$p{look_down
}} ;
98 my @elem = $container->look_down(@look_down) ;
102 for my $elem (@elem) {
103 $elem->detach if $detached++ >= $p{leave
};
107 sub HTML
::Element
::hash_map
{ ## no critic (RequireArgUnpacking)
108 my $container = shift;
110 my %p = validate
(@_, {
111 hash
=> { type
=> HASHREF
},
113 excluding
=> { type
=> ARRAYREF
, default => [] },
114 debug
=> { default => 0 },
117 warn 'The container tag is ', $container->tag if $p{debug
} ;
118 warn 'hash' . Dumper
($p{hash
}) if $p{debug
} ;
119 #warn 'at_under' . Dumper(\@_) if $p{debug} ;
121 my @same_as = $container->look_down( $p{to_attr
} => qr/.+/s ) ;
123 warn 'Found ' . scalar(@same_as) . ' nodes' if $p{debug
} ;
125 for my $same_as (@same_as) {
126 my $attr_val = $same_as->attr($p{to_attr
}) ;
127 if (first
{ $attr_val eq $_ } @
{$p{excluding
}}) {
128 warn "excluding $attr_val" if $p{debug
} ;
131 warn "processing $attr_val" if $p{debug
} ;
132 $same_as->replace_content($p{hash
}->{$attr_val});
136 sub HTML
::Element
::hashmap
{
137 my ($container, $attr_name, $hashref, $excluding, $debug) = @_;
141 $container->hash_map(
143 to_attr
=> $attr_name,
144 excluding
=> $excluding,
149 sub HTML
::Element
::passover
{
150 my ($tree, @to_preserve) = @_;
152 warn "ARGS: my ($tree, @to_preserve)" if $DEBUG;
153 warn $tree->as_HTML(undef, ' ') if $DEBUG;
155 my $exodus = $tree->look_down(id
=> $to_preserve[0]);
157 warn "E: $exodus" if $DEBUG;
159 my @s = HTML
::Element
::siblings
($exodus);
163 $s->delete unless first
{ $s->attr('id') eq $_ } @to_preserve;
166 return $exodus; # Goodbye Egypt! http://en.wikipedia.org/wiki/Passover
169 sub HTML
::Element
::sibdex
{
171 firstidx
{ $_ eq $element } $element->siblings
174 sub HTML
::Element
::addr
{ goto &HTML
::Element
::sibdex
}
176 sub HTML
::Element
::replace_content
{
178 $elem->delete_content;
179 $elem->push_content(@_);
182 sub HTML
::Element
::wrap_content
{
183 my($self, $wrap) = @_;
184 my $content = $self->content;
186 $wrap->push_content(@
$content);
190 $self->push_content($wrap);
195 sub HTML
::Element
::Library
::super_literal
{
197 HTML
::Element
->new('~literal', text
=> $text);
200 sub HTML
::Element
::position
{
201 # Report coordinates by chasing addr's up the
202 # HTML::ElementSuper tree. We know we've reached
203 # the top when a) there is no parent, or b) the
204 # parent is some HTML::Element unable to report
210 unshift @pos, $a if defined $a;
216 sub HTML
::Element
::content_handler
{
217 my ($tree, %content_hash) = @_;
219 for my $k (keys %content_hash) {
220 $tree->set_child_content(id
=> $k, $content_hash{$k});
224 sub HTML
::Element
::assign
{ goto &HTML
::Element
::content_handler
}
233 sub HTML
::Element
::iter
{
234 my ($tree, $p, @data) = @_;
236 # warn 'P: ' , $p->attr('id') ;
237 # warn 'H: ' , $p->as_HTML;
239 # my $id_incr = make_counter;
241 my $new_item = clone
$p;
242 $new_item->replace_content($_);
246 $p->replace_with(@item);
249 sub HTML
::Element
::iter2
{ ## no critic (RequireArgUnpacking)
252 #warn "INPUT TO TABLE2: ", Dumper \@_;
256 wrapper_ld
=> { default => ['_tag' => 'dl'] },
258 wrapper_proc
=> { default => undef },
263 $tr->look_down('_tag' => 'dt'),
264 $tr->look_down('_tag' => 'dd')
269 my ($wrapper_data) = @_;
270 shift @
{$wrapper_data};
274 my ($item_elems, $item_data, $row_count) = @_;
275 $item_elems->[$_]->replace_content($item_data->[$_]) for (0,1) ;
280 my ($container, @item_elems) = @_;
281 $container->splice_content(0, 2, @item_elems);
284 debug
=> {default => 0}
288 warn 'wrapper_data: ' . Dumper
$p{wrapper_data
} if $p{debug
} ;
290 my $container = ref_or_ld
($tree, $p{wrapper_ld
});
291 warn 'container: ' . $container if $p{debug
} ;
292 warn 'wrapper_(preproc): ' . $container->as_HTML if $p{debug
} ;
293 $p{wrapper_proc
}->($container) if defined $p{wrapper_proc
} ;
294 warn 'wrapper_(postproc): ' . $container->as_HTML if $p{debug
} ;
296 my $_item_elems = $p{item_ld
}->($container);
301 my $item_data = $p{item_data
}->($p{wrapper_data
});
302 last unless defined $item_data;
304 warn Dumper
('item_data', $item_data) if $p{debug
};
306 my $item_elems = [ map { $_->clone } @
{$_item_elems} ] ;
309 for (@
{$item_elems}) {
310 warn 'ITEM_ELEMS ', $_->as_HTML if $p{debug
};
314 my $new_item_elems = $p{item_proc
}->($item_elems, $item_data, ++$row_count);
317 for (@
{$new_item_elems}) {
318 warn 'NEWITEM_ELEMS ', $_->as_HTML if $p{debug
};
322 push @item_elem, @
{$new_item_elems} ;
325 warn 'pushing ' . @item_elem . ' elems' if $p{debug
} ;
327 $p{splice}->($container, @item_elem);
330 sub HTML
::Element
::dual_iter
{
331 my ($parent, $data) = @_;
333 my ($prototype_a, $prototype_b) = $parent->content_list;
335 # my $id_incr = make_counter;
339 @
$data %2 == 0 or confess
'dataset does not contain an even number of members';
341 my @iterable_data = ngroup
2 => @
$data;
344 my ($new_a, $new_b) = map { clone
$_ } ($prototype_a, $prototype_b) ;
345 $new_a->splice_content(0,1, $_->[0]);
346 $new_b->splice_content(0,1, $_->[1]);
347 #$_->attr('id', $id_incr->($_->attr('id'))) for ($new_a, $new_b) ;
351 $parent->splice_content(0, 2, @item);
354 sub HTML
::Element
::set_child_content
{ ## no critic (RequireArgUnpacking)
359 my $content_tag = $tree->look_down(@look_down);
361 unless ($content_tag) {
362 warn "criteria [@look_down] not found";
366 $content_tag->replace_content($content);
369 sub HTML
::Element
::highlander
{
370 my ($tree, $local_root_id, $aref, @arg) = @_;
372 ref $aref eq 'ARRAY' or confess
'must supply array reference';
375 @aref % 2 == 0 or confess
'supplied array ref must have an even number of entries';
377 warn __PACKAGE__
if $DEBUG;
380 while (my ($id, $test) = splice @aref, 0, 2) {
388 my @id_survivor = (id
=> $survivor);
389 my $survivor_node = $tree->look_down(@id_survivor);
391 # warn $local_root_id;
394 warn "survivor: $survivor" if $DEBUG;
395 warn 'tree: ' . $tree->as_HTML if $DEBUG;
397 $survivor_node or die "search for @id_survivor failed in tree($tree): " . $tree->as_HTML;
399 my $survivor_node_parent = $survivor_node->parent;
400 $survivor_node = $survivor_node->clone;
401 $survivor_node_parent->replace_content($survivor_node);
403 warn 'new tree: ' . $tree->as_HTML if $DEBUG;
408 sub HTML
::Element
::highlander2
{ ## no critic (RequireArgUnpacking)
411 my %p = validate
(@_, {
412 cond
=> { type
=> ARRAYREF
},
417 debug
=> { default => 0 }
420 my @cond = @
{$p{cond
}};
421 @cond % 2 == 0 or confess
'supplied array ref must have an even number of entries';
423 warn __PACKAGE__
if $p{debug
};
425 my @cond_arg = @
{$p{cond_arg
}};
427 my $survivor; my $then;
428 while (my ($id, $if_then) = splice @cond, 0, 2) {
429 warn $id if $p{debug
};
432 if (ref $if_then eq 'ARRAY') {
433 ($if, $_then) = @
$if_then;
435 ($if, $_then) = ($if_then, sub {});
438 if ($if->(@cond_arg)) {
445 my @ld = (ref $survivor eq 'ARRAY') ? @
$survivor : (id
=> $survivor);
447 warn 'survivor: ', $survivor if $p{debug
};
448 warn 'survivor_ld: ', Dumper \
@ld if $p{debug
};
450 my $survivor_node = $tree->look_down(@ld);
452 $survivor_node or confess
"search for @ld failed in tree($tree): " . $tree->as_HTML;
454 my $survivor_node_parent = $survivor_node->parent;
455 $survivor_node = $survivor_node->clone;
456 $survivor_node_parent->replace_content($survivor_node);
458 # **************** NEW FUNCTIONALITY *******************
459 # apply transforms on survivor node
461 warn 'SURV::pre_trans ' . $survivor_node->as_HTML if $p{debug
};
462 $then->($survivor_node, @cond_arg);
463 warn 'SURV::post_trans ' . $survivor_node->as_HTML if $p{debug
};
464 # **************** NEW FUNCTIONALITY *******************
469 sub overwrite_action
{
470 my ($mute_node, %X) = @_;
472 $mute_node->attr($X{local_attr
}{name
} => $X{local_attr
}{value
}{new
});
475 sub HTML
::Element
::overwrite_attr
{
478 $tree->mute_elem(@_, \
&overwrite_action
);
481 sub HTML
::Element
::mute_elem
{
482 my ($tree, $mute_attr, $closures, $post_hook) = @_;
484 my @mute_node = $tree->look_down($mute_attr => qr/.*/s) ;
486 for my $mute_node (@mute_node) {
487 my ($local_attr,$mute_key) = split /\s+/s, $mute_node->attr($mute_attr);
488 my $local_attr_value_current = $mute_node->attr($local_attr);
489 my $local_attr_value_new = $closures->{$mute_key}->($tree, $mute_node, $local_attr_value_current);
496 current
=> $local_attr_value_current,
497 new
=> $local_attr_value_new
506 sub HTML
::Element
::table
{
507 my ($s, %table) = @_;
510 # Get the table element
511 $table->{table_node
} = $s->look_down(id
=> $table{gi_table
});
512 $table->{table_node
} or confess
"table tag not found via (id => $table{gi_table}";
514 # Get the prototype tr element(s)
515 my @table_gi_tr = listify
$table{gi_tr
} ;
516 my @iter_node = map {
517 my $tr = $table->{table_node
}->look_down(id
=> $_);
518 $tr or confess
"tr with id => $_ not found";
522 warn 'found ' . @iter_node . ' iter nodes ' if $DEBUG;
523 my $iter_node = List
::Rotation
::Cycle
->new(@iter_node);
526 warn Dumper
($iter_node, \
@iter_node) if $DEBUG;
528 # $table->{content} = $table{content};
529 # $table->{parent} = $table->{table_node}->parent;
531 # $table->{table_node}->detach;
532 # $_->detach for @iter_node;
537 my $row = $table{tr_data
}->($table, $table{table_data
});
538 last unless defined $row;
540 # get a sample table row and clone it.
541 my $I = $iter_node->next;
542 warn "I: $I" if $DEBUG;
543 my $new_iter_node = $I->clone;
545 $table{td_data
}->($new_iter_node, $row);
546 push @table_rows, $new_iter_node;
550 my $replace_with_elem = $s->look_down(id
=> shift @table_gi_tr) ;
551 $s->look_down(id
=> $_)->detach for @table_gi_tr;
552 $replace_with_elem->replace_with(@table_rows);
557 my ($tree, $slot) = @_;
559 if (ref($slot) eq 'CODE') {
562 $tree->look_down(@
$slot);
566 sub HTML
::Element
::table2
{ ## no critic (RequireArgUnpacking)
571 table_ld
=> { default => ['_tag' => 'table'] },
573 table_proc
=> { default => undef },
574 tr_ld
=> { default => ['_tag' => 'tr'] },
577 my ($self, $data) = @_;
580 tr_base_id
=> { default => undef },
581 tr_proc
=> { default => sub {} },
583 debug
=> {default => 0}
587 warn 'INPUT TO TABLE2: ', Dumper \
@_ if $p{debug
};
588 warn 'table_data: ' . Dumper
$p{table_data
} if $p{debug
} ;
592 # Get the table element
593 $table->{table_node
} = ref_or_ld
( $tree, $p{table_ld
} ) ;
594 $table->{table_node
} or confess
'table tag not found via ' . Dumper
($p{table_ld
}) ;
596 warn 'table: ' . $table->{table_node
}->as_HTML if $p{debug
};
598 # Get the prototype tr element(s)
599 my @proto_tr = ref_or_ld
( $table->{table_node
}, $p{tr_ld
} ) ;
601 warn 'found ' . @proto_tr . ' iter nodes' if $p{debug
};
603 return unless @proto_tr;
606 warn $_->as_HTML for @proto_tr;
608 my $proto_tr = List
::Rotation
::Cycle
->new(@proto_tr);
610 my $tr_parent = $proto_tr[0]->parent;
611 warn 'parent element of trs: ' . $tr_parent->as_HTML if $p{debug
};
618 my $row = $p{tr_data
}->($table, $p{table_data
}, $row_count);
619 warn 'data row: ' . Dumper
$row if $p{debug
};
620 last unless defined $row;
622 # wont work: my $new_iter_node = $table->{iter_node}->clone;
623 my $new_tr_node = $proto_tr->next->clone;
624 warn "new_tr_node: $new_tr_node" if $p{debug
};
626 $p{tr_proc
}->($tree, $new_tr_node, $row, $p{tr_base_id
}, ++$row_count) if defined $p{tr_proc
};
628 warn 'data row redux: ' . Dumper
$row if $p{debug
};
630 $p{td_proc
}->($new_tr_node, $row);
631 push @table_rows, $new_tr_node;
634 $_->detach for @proto_tr;
636 $tr_parent->push_content(@table_rows) if (@table_rows) ;
639 sub HTML
::Element
::unroll_select
{
640 my ($s, %select) = @_;
643 warn 'Select Hash: ' . Dumper
(\
%select) if $select{debug
};
645 my $select_node = $s->look_down(id
=> $select{select_label
});
646 warn "Select Node: $select_node" if $select{debug
};
648 unless ($select{append
}) {
649 for my $option ($select_node->look_down('_tag' => 'option')) {
654 my $option = HTML
::Element
->new('option');
655 warn "Option Node: $option" if $select{debug
};
659 while (my $row = $select{data_iter
}->($select{data
})) {
660 warn 'Data Row: ' . Dumper
($row) if $select{debug
};
661 my $o = $option->clone;
662 $o->attr('value', $select{option_value
}->($row));
663 $o->attr('SELECTED', 1) if (exists $select{option_selected
} and $select{option_selected
}->($row));
665 $o->replace_content($select{option_content
}->($row));
666 $select_node->push_content($o);
667 warn $o->as_HTML if $select{debug
};
671 sub HTML
::Element
::set_sibling_content
{
672 my ($elt, $content) = @_;
674 $elt->parent->splice_content($elt->pindex + 1, 1, $content);
677 sub HTML
::TreeBuilder
::parse_string
{
678 my ($package, $string) = @_;
680 my $h = HTML
::TreeBuilder
->new;
681 HTML
::TreeBuilder
->parse($string);
691 HTML::Element::Library - HTML::Element convenience functions
695 use HTML::Element::Library;
696 use HTML::TreeBuilder;
700 This method provides API calls for common actions on trees when using
705 The test suite contains examples of each of these methods in a file
708 =head2 Positional Querying Methods
710 =head3 $elem->siblings
712 Return a list of all nodes under the same parent.
716 Return the index of C<$elem> into the array of siblings of which it is
717 a part. L<HTML::ElementSuper> calls this method C<addr> but I don't
718 think that is a descriptive name. And such naming is deceptively close
719 to the C<address> function of C<HTML::Element>. HOWEVER, in the
720 interest of backwards compatibility, both methods are available.
726 =head3 $elem->position()
728 Returns the coordinates of this element in the tree it inhabits. This
729 is accomplished by succesively calling addr() on ancestor elements
730 until either a) an element that does not support these methods is
731 found, or b) there are no more parents. The resulting list is the
732 n-dimensional coordinates of the element in the tree.
734 =head2 Element Decoration Methods
736 =head3 HTML::Element::Library::super_literal($text)
738 In L<HTML::Element>, Sean Burke discusses super-literals. They are
739 text which does not get escaped. Great for includng Javascript in
740 HTML. Also great for including foreign language into a document.
742 So, you basically toss C<super_literal> your text and back comes your
743 text wrapped in a C<~literal> element.
745 One of these days, I'll around to writing a nice C<EXPORT> section.
747 =head2 Tree Rewriting Methods
749 =head3 "de-prepping" HTML
751 Oftentimes, the HTML to be worked with will have multiple sample rows:
760 But, before you begin to rewrite the HTML with your model data, you
761 typically only want 1 or 2 sample rows.
763 Thus, you want to "crunch" the multiple sample rows to a specified
764 amount. Hence the C<crunch> method:
766 $tree->crunch(look_down => [ '_tag' => 'li' ], leave => 2) ;
768 The C<leave> argument defaults to 1 if not given. The call above would
769 "crunch" the above 4 sample rows to:
776 =head3 Simplifying calls to HTML::FillInForm
778 Since HTML::FillInForm gets and returns strings, using HTML::Element
779 instances becomes tedious:
781 1. Seamstress has an HTML tree that it wants the form filled in on
782 2. Seamstress converts this tree to a string
783 3. FillInForm parses the string into an HTML tree and then fills in the form
784 4. FillInForm converts the HTML tree to a string
785 5. Seamstress re-parses the HTML for additional processing
787 I've filed a bug about this:
788 L<https://rt.cpan.org/Ticket/Display.html?id=44105>
790 This function, fillinform, allows you to pass a tree to fillinform
791 (along with your data structure) and get back a tree:
793 my $new_tree = $html_tree->fillinform($data_structure);
795 =head3 Mapping a hashref to HTML elements
797 It is very common to get a hashref of data from some external source -
798 flat file, database, XML, etc. Therefore, it is important to have a
799 convenient way of mapping this data to HTML.
801 As it turns out, there are 3 ways to do this in
802 HTML::Element::Library. The most strict and structured way to do this
803 is with C<content_handler>. Two other methods, C<hashmap> and
804 C<datamap> require less manual mapping and may prove even more easy to
805 use in certain cases.
807 As is usual with Perl, a practical example is always best. So let's
808 take some sample HTML:
811 <span id="name">?</span>
812 <span id="email">?</span>
813 <span id="gender">?</span>
815 Now, let's say our data structure is this:
817 $ref = { email => 'jim@beam.com', gender => 'lots' } ;
819 And let's start with the most strict way to get what you want:
821 $tree->content_handler(email => $ref->{email} , gender => $ref->{gender}) ;
823 In this case, you manually state the mapping between id tags and
824 hashref keys and then C<content_handler> retrieves the hashref data
825 and pops it in the specified place.
827 Now let's look at the two (actually 2 and a half) other hash-mapping
830 $tree->hashmap(id => $ref);
832 Now, what this function does is super-destructive. It finds every
833 element in the tree with an attribute named id (since 'id' is a
834 parameter, it could find every element with some other attribute also)
835 and replaces the content of those elements with the hashref value.
837 So, in the case above, the
839 <span id="name">?</span>
843 <span id="name"></span>
845 (it would be blank) - because there is nothing in the hash with that
846 value, so it substituted
850 which was blank and emptied the contents.
852 Now, let's assume we want to protect name from being auto-assigned.
855 $tree->hashmap(id => $ref, ['name']);
857 That last array ref is an exclusion list.
859 But wouldnt it be nice if you could do a hashmap, but only assigned
860 things which are defined in the hashref? C<< defmap() >> to the
863 $tree->defmap(id => $ref);
867 <span id="name">?</span>
871 =head4 $elem->hashmap($attr_name, \%hashref, \@excluded, $debug)
873 This method is designed to take a hashref and populate a series of
874 elements. For example:
877 <tr sclass="tr" class="alt" align="left" valign="top">
878 <td smap="people_id">1</td>
879 <td smap="phone">(877) 255-3239</td>
880 <td smap="password">*********</td>
884 In the table above, there are several attributes named C<< smap >>. If
885 we have a hashref whose keys are the same:
887 my %data = (people_id => 888, phone => '444-4444', password => 'dont-you-dare-render');
889 Then a single API call allows us to populate the HTML while excluding
892 $tree->hashmap(smap => \%data, ['password']);
894 Note: the other way to prevent rendering some of the hash mapping is
895 to not give that element the attr you plan to use for hash mapping.
897 Also note: the function C<< hashmap >> has a simple easy-to-type API.
898 Interally, it calls C<< hash_map >> (which has a more verbose keyword
899 calling API). Thus, the above call to C<hashmap()> results in this
902 $tree->hash_map(hash => \%data, to_attr => 'sid', excluding => ['password']);
904 =head4 $elem->defmap($attr_name, \%hashref, $debug)
906 C<defmap> was described above.
908 =head3 $elem->replace_content(@new_elem)
910 Replaces all of C<$elem>'s content with C<@new_elem>.
912 =head3 $elem->wrap_content($wrapper_element)
914 Wraps the existing content in the provided element. If the provided
915 element happens to be a non-element, a push_content is performed
918 =head3 $elem->set_child_content(@look_down, $content)
920 This method looks down $tree using the criteria specified in
921 @look_down using the the HTML::Element look_down() method.
923 After finding the node, it detaches the node's content and pushes
924 $content as the node's content.
926 =head3 $tree->content_handler(%id_content)
928 This is a convenience method. Because the look_down criteria will
935 <a id=fixme href=http://www.somesite.org>replace_content</a>
937 You can call this method to shorten your typing a bit. You can simply
940 $elem->content_handler( fixme => 'new text' )
944 $elem->set_child_content(sid => 'fixme', 'new text')
946 ALSO NOTE: you can pass a hash whose keys are C<id>s and whose values
947 are the content you want there and it will perform the replacement on
950 my %id_content = (name => "Terrence Brannon",
951 email => 'tbrannon@in.com',
953 content => $main_content);
954 $tree->content_handler(%id_content);
956 =head3 $tree->highlander($subtree_span_id, $conditionals, @conditionals_args)
958 This allows for "if-then-else" style processing. Highlander was a
959 movie in which only one would survive. Well, in terms of a tree when
960 looking at a structure that you want to process in C<if-then-else>
961 style, only one child will survive. For example, given this HTML
964 <span klass="highlander" id="age_dialog">
966 Hello, does your mother know you're
967 using her AOL account?
970 Sorry, you're not old enough to enter
971 (and too dumb to lie about your age)
978 We only want one child of the C<span> tag with id C<age_dialog> to
979 remain based on the age of the person visiting the page.
981 So, let's setup a call that will prune the subtree as a function of
986 my $tree = HTML::TreeBuilder->new_from_file('t/html/highlander.html');
991 under10 => sub { $_[0] < 10},
992 under18 => sub { $_[0] < 18},
998 And there we have it. If the age is less than 10, then the node with
999 id C<under10> remains. For age less than 18, the node with id
1000 C<under18> remains. Otherwise our "else" condition fires and the child
1001 with id C<welcome> remains.
1003 =head3 $tree->passover(@id_of_element)
1005 In some cases, you know exactly which element(s) should survive. In
1006 this case, you can simply call C<passover> to remove it's (their)
1007 siblings. For the HTML above, you could delete C<under10> and
1008 C<welcome> by simply calling:
1010 $tree->passover('under18');
1012 Because passover takes an array, you can specify several children to
1015 =head3 $tree->highlander2($tree, $conditionals, @conditionals_args)
1017 Right around the same time that C<table2()> came into being,
1018 Seamstress began to tackle tougher and tougher processing problems. It
1019 became clear that a more powerful highlander was needed... one that
1020 not only snipped the tree of the nodes that should not survive, but
1021 one that allows for post-processing of the survivor node. And one that
1022 was more flexible with how to find the nodes to snip.
1024 Thus (drum roll) C<highlander2()>.
1026 So let's look at our HTML which requires post-selection processing:
1028 <span klass="highlander" id="age_dialog">
1030 Hello, little <span id=age>AGE</span>-year old,
1031 does your mother know you're using her AOL account?
1034 Sorry, you're only <span id=age>AGE</span>
1035 (and too dumb to lie about your age)
1038 Welcome, isn't it good to be <span id=age>AGE</span> years old?
1042 In this case, a branch survives, but it has dummy data in it. We must
1043 take the surviving segment of HTML and rewrite the age C<span> with
1044 the age. Here is how we use C<highlander2()> to do so:
1049 $branch->look_down(id => 'age')->replace_content($age);
1052 my $if_then = $tree->look_down(id => 'age_dialog');
1054 $if_then->highlander2(
1069 cond_arg => [ $age ]
1072 We pass it the tree (C<$if_then>), an arrayref of conditions (C<cond>)
1073 and an arrayref of arguments which are passed to the C<cond>s and to
1074 the replacement subs.
1076 The C<under10>, C<under18> and C<welcome> are id attributes in the
1077 tree of the siblings of which only one will survive. However, should
1078 you need to do more complex look-downs to find the survivor, then
1079 supply an array ref instead of a simple scalar:
1081 $if_then->highlander2(
1083 [class => 'r12'] => [
1087 [class => 'z22'] => [
1091 [class => 'w88'] => [
1096 cond_arg => [ $age ]
1099 =head3 $tree->overwrite_attr($mutation_attr => $mutating_closures)
1101 This method is designed for taking a tree and reworking a set of nodes
1102 in a stereotyped fashion. For instance let's say you have 3 remote
1103 image archives, but you don't want to put long URLs in your img src
1104 tags for reasons of abstraction, re-use and brevity. So instead you do
1107 <img src="/img/smiley-face.jpg" fixup="src lnc">
1108 <img src="/img/hot-babe.jpg" fixup="src playboy">
1109 <img src="/img/footer.jpg" fixup="src foobar">
1111 and then when the tree of HTML is being processed, you make this call:
1114 lnc => sub { my ($tree, $mute_node, $attr_value)= @_; "http://lnc.usc.edu$attr_value" },
1115 playboy => sub { my ($tree, $mute_node, $attr_value)= @_; "http://playboy.com$attr_value" }
1116 foobar => sub { my ($tree, $mute_node, $attr_value)= @_; "http://foobar.info$attr_value" }
1119 $tree->overwrite_attr(fixup => \%closures) ;
1121 and the tags come out modified like so:
1123 <img src="http://lnc.usc.edu/img/smiley-face.jpg" fixup="src lnc">
1124 <img src="http://playboy.com/img/hot-babe.jpg" fixup="src playboy">
1125 <img src="http://foobar.info/img/footer.jpg" fixup="src foobar">
1127 =head3 $tree->mute_elem($mutation_attr => $mutating_closures, [ $post_hook ] )
1129 This is a generalization of C<overwrite_attr>. C<overwrite_attr>
1130 assumes the return value of the closure is supposed overwrite an
1131 attribute value and does it for you. C<mute_elem> is a more general
1132 function which does nothing but hand the closure the element and let
1133 it mutate it as it jolly well pleases :)
1135 In fact, here is the implementation of C<overwrite_attr> to give you a
1136 taste of how C<mute_attr> is used:
1138 sub overwrite_action {
1139 my ($mute_node, %X) = @_;
1141 $mute_node->attr($X{local_attr}{name} => $X{local_attr}{value}{new});
1145 sub HTML::Element::overwrite_attr {
1148 $tree->mute_elem(@_, \&overwrite_action);
1151 =head2 Tree-Building Methods
1153 =head3 Unrolling an array via a single sample element (<ul> container)
1155 This is best described by example. Given this HTML:
1157 <strong>Here are the things I need from the store:</strong>
1159 <li class="store_items">Sample item</li>
1162 We can unroll it like so:
1164 my $li = $tree->look_down(class => 'store_items');
1166 my @items = qw(bread butter vodka);
1168 $tree->iter($li => @items);
1174 <body>Here are the things I need from the store:
1176 <li class="store_items">bread</li>
1177 <li class="store_items">butter</li>
1178 <li class="store_items">vodka</li>
1183 Now, you might be wondering why the API call is:
1185 $tree->iter($li => @items)
1191 and there is no good answer. The latter would be more concise and it
1192 is what I should have done.
1194 =head3 Unrolling an array via n sample elements (<dl> container)
1196 C<iter()> was fine for awhile, but some things (e.g. definition lists)
1197 need a more general function to make them easy to do. Hence
1198 C<iter2()>. This function will be explained by example of unrolling a
1199 simple definition list.
1201 So here's our mock-up HTML from the designer:
1203 <dl class="dual_iter" id="service_plan">
1205 <dd>A person who draws blood.</dd>
1208 <dd>A clone of Iggy Pop.</dd>
1211 <dd>A relative of Edgar Allan Poe.</dd>
1213 <dt class="adstyle">sample header</dt>
1214 <dd class="adstyle2">sample data</dd>
1218 And we want to unroll our data set:
1221 ['the pros' => 'never have to worry about service again'],
1222 ['the cons' => 'upfront extra charge on purchase'],
1223 ['our choice' => 'go with the extended service plan']
1227 Now, let's make this problem a bit harder to show off the power of
1228 C<iter2()>. Let's assume that we want only the last <dt> and it's
1229 accompanying <dd> (the one with "sample data") to be used as the
1230 sample data for unrolling with our data set. Let's further assume that
1231 we want them to remain in the final output.
1233 So now, the API to C<iter2()> will be discussed and we will explain
1234 how our goal of getting our data into HTML fits into the API.
1240 This is how to look down and find the container of all the elements we
1241 will be unrolling. The <dl> tag is the container for the dt and dd
1242 tags we will be unrolling.
1244 If you pass an anonymous subroutine, then it is presumed that
1245 execution of this subroutine will return the HTML::Element
1246 representing the container tag. If you pass an array ref, then this
1247 will be dereferenced and passed to C<HTML::Element::look_down()>.
1249 default value: C<< ['_tag' => 'dl'] >>
1251 Based on the mock HTML above, this default is fine for finding our
1252 container tag. So let's move on.
1254 =item * wrapper_data
1256 This is an array reference of data that we will be putting into the
1257 container. You must supply this. C<@items> above is our
1260 =item * wrapper_proc
1262 After we find the container via C<wrapper_ld>, we may want to
1263 pre-process some aspect of this tree. In our case the first two sets
1264 of dt and dd need to be removed, leaving the last dt and dd. So, we
1265 supply a C<wrapper_proc> which will do this.
1271 This anonymous subroutine returns an array ref of C<HTML::Element>s
1272 that will be cloned and populated with item data (item data is a "row"
1273 of C<wrapper_data>).
1275 default: returns an arrayref consisting of the dt and dd element
1276 inside the container.
1280 This is a subroutine that takes C<wrapper_data> and retrieves one
1281 "row" to be "pasted" into the array ref of C<HTML::Element>s found via
1282 C<item_ld>. I hope that makes sense.
1284 default: shifts C<wrapper_data>.
1288 This is a subroutine that takes the C<item_data> and the
1289 C<HTML::Element>s found via C<item_ld> and produces an arrayref of
1290 C<HTML::Element>s which will eventually be spliced into the container.
1292 Note that this subroutine MUST return the new items. This is done So
1293 that more items than were passed in can be returned. This is useful
1294 when, for example, you must return 2 dts for an input data item. And
1295 when would you do this? When a single term has multiple spellings for
1298 default: expects C<item_data> to be an arrayref of two elements and
1299 C<item_elems> to be an arrayref of two C<HTML::Element>s. It replaces
1300 the content of the C<HTML::Element>s with the C<item_data>.
1304 After building up an array of C<@item_elems>, the subroutine passed as
1305 C<splice> will be given the parent container HTML::Element and the
1306 C<@item_elems>. How the C<@item_elems> end up in the container is up
1307 to this routine: it could put half of them in. It could unshift them
1310 default: C<< $container->splice_content(0, 2, @item_elems) >> In other
1311 words, kill the 2 sample elements with the newly generated @item_elems
1315 So now that we have documented the API, let's see the call we need:
1318 # default wrapper_ld ok.
1319 wrapper_data => \@items,
1320 wrapper_proc => sub {
1321 my ($container) = @_;
1323 # only keep the last 2 dts and dds
1324 my @content_list = $container->content_list;
1325 $container->splice_content(0, @content_list - 2);
1328 # default item_ld is fine.
1329 # default item_data is fine.
1330 # default item_proc is fine.
1332 my ($container, @item_elems) = @_;
1333 $container->unshift_content(@item_elems);
1338 =head3 Select Unrolling
1340 The C<unroll_select> method has this API:
1342 $tree->unroll_select(
1343 select_label => $id_label,
1344 option_value => $closure, # how to get option value from data row
1345 option_content => $closure, # how to get option content from data row
1346 option_selected => $closure, # boolean to decide if SELECTED
1347 data => $data # the data to be put into the SELECT
1348 data_iter => $closure # the thing that will get a row of data
1350 append => $boolean, # remove the sample <OPTION> data or append?
1355 $tree->unroll_select(
1356 select_label => 'clan_list',
1357 option_value => sub { my $row = shift; $row->clan_id },
1358 option_content => sub { my $row = shift; $row->clan_name },
1359 option_selected => sub { my $row = shift; $row->selected },
1360 data => \@query_results,
1361 data_iter => sub { my $data = shift; $data->next },
1366 =head2 Tree-Building Methods: Table Generation
1368 Matthew Sisk has a much more intuitive (imperative) way to generate
1369 tables via his module L<HTML::ElementTable|HTML::ElementTable>.
1371 However, for those with callback fever, the following method is
1372 available. First, we look at a nuts and bolts way to build a table
1373 using only standard L<HTML::Tree> API calls. Then the C<table> method
1374 available here is discussed.
1378 package Simple::Class;
1382 my @name = qw(bob bill brian babette bobo bix);
1383 my @age = qw(99 12 44 52 12 43);
1384 my @weight = qw(99 52 80 124 120 230);
1389 bless {}, ref($this) || $this;
1397 age => $age[rand $#age] + int rand 20,
1398 name => shift @name,
1399 weight => $weight[rand $#weight] + int rand 40
1403 Set::Array->new(@data);
1408 =head4 Sample Usage:
1410 my $data = Simple::Class->load_data;
1411 ++$_->{age} for @$data
1413 =head3 Inline Code to Unroll a Table
1418 <table id="load_data">
1419 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
1421 <td id="name"> NATURE BOY RIC FLAIR </td>
1422 <td id="age"> 35 </td>
1423 <td id="weight"> 220 </td>
1429 =head4 The manual way (*NOT* recommended)
1431 require 'simple-class.pl';
1432 use HTML::Seamstress;
1435 my $seamstress = HTML::Seamstress->new_from_file('simple.html');
1438 my $o = Simple::Class->new;
1439 my $data = $o->load_data;
1441 # find the <table> and <tr>
1442 my $table_node = $seamstress->look_down('id', 'load_data');
1443 my $iter_node = $table_node->look_down('id', 'iterate');
1444 my $table_parent = $table_node->parent;
1447 # drop the sample <table> and <tr> from the HTML
1448 # only add them in if there is data in the model
1449 # this is achieved via the $add_table flag
1451 $table_node->detach;
1455 # Get a row of model data
1456 while (my $row = shift @$data) {
1458 # We got row data. Set the flag indicating ok to hook the table into the HTML
1461 # clone the sample <tr>
1462 my $new_iter_node = $iter_node->clone;
1464 # find the tags labeled name age and weight and
1465 # set their content to the row data
1466 $new_iter_node->content_handler($_ => $row->{$_})
1467 for qw(name age weight);
1469 $table_node->push_content($new_iter_node);
1473 # reattach the table to the HTML tree if we loaded data into some table rows
1475 $table_parent->push_content($table_node) if $add_table;
1477 print $seamstress->as_HTML;
1479 =head3 $tree->table() : API call to Unroll a Table
1481 require 'simple-class.pl';
1482 use HTML::Seamstress;
1485 my $seamstress = HTML::Seamstress->new_from_file('simple.html');
1487 my $o = Simple::Class->new;
1491 # tell seamstress where to find the table, via the method call
1492 # ->look_down('id', $gi_table). Seamstress detaches the table from the
1493 # HTML tree automatically if no table rows can be built
1495 gi_table => 'load_data',
1497 # tell seamstress where to find the tr. This is a bit useless as
1498 # the <tr> usually can be found as the first child of the parent
1502 # the model data to be pushed into the table
1504 table_data => $o->load_data,
1506 # the way to take the model data and obtain one row
1507 # if the table data were a hashref, we would do:
1508 # my $key = (keys %$data)[0]; my $val = $data->{$key}; delete $data->{$key}
1511 my ($self, $data) = @_;
1515 # the way to take a row of data and fill the <td> tags
1518 my ($tr_node, $tr_data) = @_;
1519 $tr_node->content_handler($_ => $tr_data->{$_})
1520 for qw(name age weight)
1524 print $seamstress->as_HTML;
1526 =head4 Looping over Multiple Sample Rows
1531 <table id="load_data" CELLPADDING=8 BORDER=2>
1532 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
1533 <tr id="iterate1" BGCOLOR="white" >
1534 <td id="name"> NATURE BOY RIC FLAIR </td>
1535 <td id="age"> 35 </td>
1536 <td id="weight"> 220 </td>
1538 <tr id="iterate2" BGCOLOR="#CCCC99">
1539 <td id="name"> NATURE BOY RIC FLAIR </td>
1540 <td id="age"> 35 </td>
1541 <td id="weight"> 220 </td>
1546 * Only one change to last API call.
1554 gi_tr => ['iterate1', 'iterate2']
1556 =head3 $tree->table2() : New API Call to Unroll a Table
1558 After 2 or 3 years with C<table()>, I began to develop production
1559 websites with it and decided it needed a cleaner interface,
1560 particularly in the area of handling the fact that C<id> tags will be
1561 the same after cloning a table row.
1563 First, I will give a dry listing of the function's argument
1564 parameters. This will not be educational most likely. A better way to
1565 understand how to use the function is to read through the incremental
1566 unrolling of the function's interface given in conversational style
1567 after the dry listing. But take your pick. It's the same information
1568 given in two different ways.
1570 =head4 Dry/technical parameter documentation
1572 C<< $tree->table2(%param) >> takes the following arguments:
1576 =item * C<< table_ld => $look_down >> : optional
1578 How to find the C<table> element in C<$tree>. If C<$look_down> is an
1579 arrayref, then use C<look_down>. If it is a CODE ref, then call it,
1580 passing it C<$tree>.
1582 Defaults to C<< ['_tag' => 'table'] >> if not passed in.
1584 =item * C<< table_data => $tabular_data >> : required
1586 The data to fill the table with. I<Must> be passed in.
1588 =item * C<< table_proc => $code_ref >> : not implemented
1590 A subroutine to do something to the table once it is found. Not
1591 currently implemented. Not obviously necessary. Just created because
1592 there is a C<tr_proc> and C<td_proc>.
1594 =item * C<< tr_ld => $look_down >> : optional
1596 Same as C<table_ld> but for finding the table row elements. Please
1597 note that the C<tr_ld> is done on the table node that was found
1598 I<instead> of the whole HTML tree. This makes sense. The C<tr>s that
1599 you want exist below the table that was just found.
1601 Defaults to C<< ['_tag' => 'tr'] >> if not passed in.
1603 =item * C<< tr_data => $code_ref >> : optional
1605 How to take the C<table_data> and return a row. Defaults to:
1607 sub { my ($self, $data) = @_;
1611 =item * C<< tr_proc => $code_ref >> : optional
1613 Something to do to the table row we are about to add to the table we
1614 are making. Defaults to a routine which makes the C<id> attribute
1618 my ($self, $tr, $tr_data, $tr_base_id, $row_count) = @_;
1619 $tr->attr(id => sprintf "%s_%d", $tr_base_id, $row_count);
1622 =item * C<< td_proc => $code_ref >> : required
1624 This coderef will take the row of data and operate on the C<td> cells
1625 that are children of the C<tr>. See C<t/table2.t> for several usage
1628 Here's a sample one:
1631 my ($tr, $data) = @_;
1632 my @td = $tr->look_down('_tag' => 'td');
1633 for my $i (0..$#td) {
1634 $td[$i]->splice_content(0, 1, $data->[$i]);
1640 =head4 Conversational parameter documentation
1642 The first thing you need is a table. So we need a look down for that.
1643 If you don't give one, it defaults to
1647 What good is a table to display in without data to display?! So you
1648 must supply a scalar representing your tabular data source. This
1649 scalar might be an array reference, a C<next>able iterator, a DBI
1650 statement handle. Whatever it is, it can be iterated through to build
1651 up rows of table data. These two required fields (the way to find the
1652 table and the data to display in the table) are C<table_ld> and
1653 C<table_data> respectively. A little more on C<table_ld>. If this
1654 happens to be a CODE ref, then execution of the code ref is presumed
1655 to return the C<HTML::Element> representing the table in the HTML
1658 Next, we get the row or rows which serve as sample C<tr> elements by
1659 doing a C<look_down> from the C<table_elem>. While normally one sample
1660 row is enough to unroll a table, consider when you have alternating
1661 table rows. This API call would need one of each row so that it can
1662 cycle through the sample rows as it loops through the data.
1663 Alternatively, you could always just use one row and make the
1664 necessary changes to the single C<tr> row by mutating the element in
1665 C<tr_proc>, discussed below. The default C<tr_ld> is C<< ['_tag' =>
1666 'tr'] >> but you can overwrite it. Note well, if you overwrite it with
1667 a subroutine, then it is expected that the subroutine will return the
1668 C<HTML::Element>(s) which are C<tr> element(s). The reason a
1669 subroutine might be preferred is in the case that the HTML designers
1670 gave you 8 sample C<tr> rows but only one prototype row is needed. So
1671 you can write a subroutine, to splice out the 7 rows you don't need
1672 and leave the one sample row remaining so that this API call can clone
1673 it and supply it to the C<tr_proc> and C<td_proc> calls.
1675 Now, as we move through the table rows with table data, we need to do
1676 two different things on each table row:
1680 =item * get one row of data from the C<table_data> via C<tr_data>
1682 The default procedure assumes the C<table_data> is an array reference
1683 and shifts a row off of it:
1686 my ($self, $data) = @_;
1690 Your function MUST return undef when there is no more rows to lay out.
1692 =item * take the C<tr> element and mutate it via C<tr_proc>
1694 The default procedure simply makes the id of the table row unique:
1697 my ($self, $tr, $tr_data, $row_count, $root_id) = @_;
1698 $tr->attr(id => sprintf "%s_%d", $root_id, $row_count);
1703 Now that we have our row of data, we call C<td_proc> so that it can
1704 take the data and the C<td> cells in this C<tr> and process them. This
1705 function I<must> be supplied.
1707 =head3 Whither a Table with No Rows
1709 Often when a table has no rows, we want to display a message
1710 indicating this to the view. Use conditional processing to decide what
1714 <table><tr><td>No Data is Good Data</td></tr></table>
1718 <table id="load_data">
1719 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
1721 <td id="name"> NATURE BOY RIC FLAIR </td>
1722 <td id="age"> 35 </td>
1723 <td id="weight"> 220 </td>
1729 =head2 Tree-Killing Methods
1733 This removes any nodes from the tree which consist of nothing or
1734 nothing but whitespace. See also delete_ignorable_whitespace in
1737 =head2 Loltree Functions
1739 A loltree is an arrayref consisting of arrayrefs which is used by C<<
1740 new_from__lol >> in L<HTML::Element> to produce HTML trees. The CPAN
1741 distro L<XML::Element::Tolol> creates such XML trees by parsing XML
1742 files, analagous to L<XML::Toolkit>. The purpose of the functions in
1743 this section is to allow you manipulate a loltree programmatically.
1745 These could not be methods because if you bless a loltree, then
1746 HTML::Tree will barf.
1748 =head3 HTML::Element::newchild($lol, $parent_label, @newchild)
1750 Given this initial loltree:
1752 my $initial_lol = [ note => [ shopping => [ item => 'sample' ] ] ];
1756 sub shopping_items {
1757 my @shopping_items = map { [ item => _ ] } qw(bread butter beans);
1761 my $new_lol = HTML::Element::newnode($initial_lol, item => shopping_items());
1763 will replace the single sample with a list of shopping items:
1785 Thanks to kcott and the other Perlmonks in this thread:
1786 http://www.perlmonks.org/?node_id=912416
1791 =head2 L<HTML::Tree>
1793 A perl package for creating and manipulating HTML trees.
1795 =head2 L<HTML::ElementTable>
1797 An L<HTML::Tree> - based module which allows for manipulation of HTML
1798 trees using cartesian coordinations.
1800 =head2 L<HTML::Seamstress>
1802 An L<HTML::Tree> - based module inspired by XMLC
1803 (L<http://xmlc.enhydra.org>), allowing for dynamic HTML generation via
1806 =head2 Push-style templating systems
1808 A comprehensive cross-language
1809 L<list of push-style templating systems|http://perlmonks.org/?node_id=674225>.
1817 currently the API expects the subtrees to survive or be pruned to be
1820 $if_then->highlander2([
1821 under10 => sub { $_[0] < 10} ,
1822 under18 => sub { $_[0] < 18} ,
1827 $branch->look_down(id => 'age')->replace_content($age);
1832 but, it should be more flexible. the C<under10>, and C<under18> are
1833 expected to be ids in the tree... but it is not hard to have a check
1834 to see if this field is an array reference and if it, then to do a
1837 $if_then->highlander2([
1838 [class => 'under10'] => sub { $_[0] < 10} ,
1839 [class => 'under18'] => sub { $_[0] < 18} ,
1840 [class => 'welcome'] => [
1844 $branch->look_down(id => 'age')->replace_content($age);
1853 Original author Terrence Brannon, E<lt>tbone@cpan.orgE<gt>.
1855 Adopted by Marius Gavrilescu C<< <marius@ieval.ro> >>.
1857 I appreciate the feedback from M. David Moussa Leo Keita regarding
1858 some issues with the test suite, namely (1) CRLF leading to test
1859 breakage in F<t/crunch.t> and (2) using the wrong module in
1860 F<t/prune.t> thus not having the right functionality available.
1862 Many thanks to BARBIE for his RT bug report.
1864 Many thanks to perlmonk kcott for his work on array rewriting:
1865 L<http://www.perlmonks.org/?node_id=912416>. It was crucial in the
1866 development of newchild.
1868 =head1 COPYRIGHT AND LICENSE
1870 Coypright (C) 2014 by Marius Gavrilescu
1872 Copyright (C) 2004-2012 by Terrence Brannon
1874 This library is free software; you can redistribute it and/or modify
1875 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1876 at your option, any later version of Perl 5 you may have available.
This page took 0.113804 seconds and 3 git commands to generate.