title

for example. + + my $t= XML::Twig->new( twig_handlers => + { 'section/title' => sub { $_->print } } + ) + ->parsefile( 'doc.xml'); + +Here C<print } >> simply prints the current element (C<$_> is aliased +to the element in the handler). + +You can also trigger a handler on a test on an attribute: + + my $t= XML::Twig->new( twig_handlers => + { 'section[@level="1"]' => sub { $_->print } } + ); + ->parsefile( 'doc.xml'); + +You can also use C > to process an +element as soon as the start tag is found. Besides C > you +can also use C >, + +=head2 Processing just parts of an XML document + +The twig_roots mode builds only the required sub-trees from the document +Anything outside of the twig roots will just be ignored: + + my $t= XML::Twig->new( + # the twig will include just the root and selected titles + twig_roots => { 'section/title' => \&print_n_purge, + 'annex/title' => \&print_n_purge + } + ); + $t->parsefile( 'doc.xml'); + + sub print_n_purge + { my( $t, $elt)= @_; + print $elt->text; # print the text (including sub-element texts) + $t->purge; # frees the memory + } + +You can use that mode when you want to process parts of a documents but are +not interested in the rest and you don't want to pay the price, either in +time or memory, to build the tree for the it. + + +=head2 Building an XML filter + +You can combine the C and the C options to +build filters, which let you modify selected elements and will output the rest +of the document as is. + +This would convert prices in $ to prices in Euro in a document: + + my $t= XML::Twig->new( + twig_roots => { 'price' => \&convert, }, # process prices + twig_print_outside_roots => 1, # print the rest + ); + $t->parsefile( 'doc.xml'); + + sub convert + { my( $t, $price)= @_; + my $currency= $price->{'att'}->{'currency'}; # get the currency + if( $currency eq 'USD') + { $usd_price= $price->text; # get the price + # %rate is just a conversion table + my $euro_price= $usd_price * $rate{usd2euro}; + $price->set_text( $euro_price); # set the new price + $price->set_att( currency => 'EUR'); # don't forget this! + } + $price->print; # output the price + } + +=head2 XML::Twig and various versions of Perl, XML::Parser and expat: + +XML::Twig is a lot more sensitive to variations in versions of perl, +XML::Parser and expat than to the OS, so this should cover some +reasonable configurations. + +The "recommended configuration" is perl 5.8.3+ (for good Unicode +support), XML::Parser 2.31+ and expat 1.95.5+ + +See L for the +CPAN testers reports on XML::Twig, which list all tested configurations. + +An Atom feed of the CPAN Testers results is available at +L + +Finally: + +=over 4 + +=item XML::Twig does B work with expat 1.95.4 + +=item XML::Twig only works with XML::Parser 2.27 in perl 5.6.* + +Note that I can't compile XML::Parser 2.27 anymore, so I can't guarantee +that it still works + +=item XML::Parser 2.28 does not really work + +=back + +When in doubt, upgrade expat, XML::Parser and Scalar::Util + +Finally, for some optional features, XML::Twig depends on some additional +modules. The complete list, which depends somewhat on the version of Perl +that you are running, is given by running C + +=head1 Simplifying XML processing + +=over 4 + +=item Whitespaces + +Whitespaces that look non-significant are discarded, this behaviour can be +controlled using the C >, +C > and +C > options. + +=item Encoding + +You can specify that you want the output in the same encoding as the input +(provided you have valid XML, which means you have to specify the encoding +either in the document or when you create the Twig object) using the +C > option + +You can also use C> to convert the internal UTF-8 format +to the required encoding. + +=item Comments and Processing Instructions (PI) + +Comments and PI's can be hidden from the processing, but still appear in the +output (they are carried by the "real" element closer to them) + +=item Pretty Printing + +XML::Twig can output the document pretty printed so it is easier to read for +us humans. + +=item Surviving an untimely death + +XML parsers are supposed to react violently when fed improper XML. +XML::Parser just dies. + +XML::Twig provides the C > and the +C > methods which wrap the parse in an eval +and return either the parsed twig or 0 in case of failure. + +=item Private attributes + +Attributes with a name starting with # (illegal in XML) will not be +output, so you can safely use them to store temporary values during +processing. Note that you can store anything in a private attribute, +not just text, it's just a regular Perl variable, so a reference to +an object or a huge data structure is perfectly fine. + +=back + +=head1 CLASSES + +XML::Twig uses a very limited number of classes. The ones you are most likely to use +are C> of course, which represents a complete XML document, including the +document itself (the root of the document itself is C>), its handlers, its +input or output filters... The other main class is C>, which models +an XML element. Element here has a very wide definition: it can be a regular element, or +but also text, with an element C> of C<#PCDATA> (or C<#CDATA>), an entity (tag is +C<#ENT>), a Processing Instruction (C<#PI>), a comment (C<#COMMENT>). + +Those are the 2 commonly used classes. + +You might want to look the C> option if you want to subclass C. + +Attributes are just attached to their parent element, they are not objects per se. (Please +use the provided methods C> and C> to access them, if you access them +as a hash, then your code becomes implementation dependent and might break in the future). + +Other classes that are seldom used are C> and C>. + +If you use C> instead of C, elements are then created as +C> + + +=head1 METHODS + +=head2 XML::Twig + +A twig is a subclass of XML::Parser, so all XML::Parser methods can be +called on a twig object, including parse and parsefile. +C on the other hand cannot be used, see C > + + +=over 4 + +=item new + +This is a class method, the constructor for XML::Twig. Options are passed +as keyword value pairs. Recognized options are the same as XML::Parser, +plus some (in fact a lot!) XML::Twig specifics. + +New Options: + +=over 4 + +=item twig_handlers + +This argument consists of a hash C<{ expression => \&handler}> where +expression is a an I (+ some others). + +XPath expressions are limited to using the child and descendant axis +(indeed you can't specify an axis), and predicates cannot be nested. +You can use the C, or C<< string() >> function (except +in C triggers). + +Additionally you can use regexps (/ delimited) to match attribute +and string values. + +Examples: + + foo + foo/bar + foo//bar + /foo/bar + /foo//bar + /foo/bar[@att1 = "val1" and @att2 = "val2"]/baz[@a >= 1] + foo[string()=~ /^duh!+/] + /foo[string(bar)=~ /\d+/]/baz[@att != 3] + +#CDATA can be used to call a handler for a CDATA section. +#COMMENT can be used to call a handler for comments + +Some additional (non-XPath) expressions are also provided for convenience: + +=over 4 + +=item processing instructions + +C<'?'> or C<'#PI'> triggers the handler for any processing instruction, +and C<< '?' >> or C<< '#PI ' >> triggers a handler for processing +instruction with the given target( ex: C<'#PI xml-stylesheet'>). + +=item level() + +Triggers the handler on any element at that level in the tree (root is level 1) + +=item _all_ + +Triggers the handler for B elements in the tree + +=item _default_ + +Triggers the handler for each element that does NOT have any other handler. + +=back + +Expressions are evaluated against the input document. +Which means that even if you have changed the tag of an element (changing the +tag of a parent element from a handler for example) the change will not impact +the expression evaluation. There is an exception to this: "private" attributes +(which name start with a '#', and can only be created during the parsing, as +they are not valid XML) are checked against the current twig. + +Handlers are triggered in fixed order, sorted by their type (xpath expressions +first, then regexps, then level), then by whether they specify a full path +(starting at the root element) or +not, then by number of steps in the expression , then number of +predicates, then number of tests in predicates. Handlers where the last +step does not specify a step (C) are triggered after other XPath +handlers. Finally C<_all_> handlers are triggered last. + +B: once a handler has been triggered if it returns 0 then no other +handler is called, except a C<_all_> handler which will be called anyway. + +If a handler returns a true value and other handlers apply, then the next +applicable handler will be called. Repeat, rinse, lather..; The exception +to that rule is when the C> +option is set, in which case only the first handler will be called. + +Note that it might be a good idea to explicitly return a short true value +(like 1) from handlers: this ensures that other applicable handlers are +called even if the last statement for the handler happens to evaluate to +false. This might also speedup the code by avoiding the result of the last +statement of the code to be copied and passed to the code managing handlers. +It can really pay to have 1 instead of a long string returned. + +When the closing tag for an element is parsed the corresponding handler is +called, with 2 arguments: the twig and the C >. The twig includes +the document tree that has been built so far, the element is the complete +sub-tree for the element. The fact that the handler is called only when the +closing tag for the element is found means that handlers for inner elements +are called before handlers for outer elements. + +C<$_> is also set to the element, so it is easy to write inline handlers like + + para => sub { $_->set_tag( 'p'); } + +Text is stored in elements whose tag name is #PCDATA (due to mixed content, +text and sub-element in an element there is no way to store the text as just +an attribute of the enclosing element). + +B: if you have used purge or flush on the twig the element might not +be complete, some of its children might have been entirely flushed or purged, +and the start tag might even have been printed (by C) already, so changing +its tag might not give the expected result. + + +=item twig_roots + +This argument let's you build the tree only for those elements you are +interested in. + + Example: my $t= XML::Twig->new( twig_roots => { title => 1, subtitle => 1}); + $t->parsefile( file); + my $t= XML::Twig->new( twig_roots => { 'section/title' => 1}); + $t->parsefile( file); + + +return a twig containing a document including only C and C<subtitle> +elements, as children of the root element. + +You can use I<generic_attribute_condition>, I<attribute_condition>, +I<full_path>, I<partial_path>, I<tag>, I<tag_regexp>, I<_default_> and +I<_all_> to trigger the building of the twig. +I<string_condition> and I<regexp_condition> cannot be used as the content +of the element, and the string, have not yet been parsed when the condition +is checked. + +B<WARNING>: path are checked for the document. Even if the C<twig_roots> option +is used they will be checked against the full document tree, not the virtual +tree created by XML::Twig + + +B<WARNING>: twig_roots elements should NOT be nested, that would hopelessly +confuse XML::Twig ;--( + +Note: you can set handlers (twig_handlers) using twig_roots + Example: my $t= XML::Twig->new( twig_roots => + { title => sub { $_[1]->print;}, + subtitle => \&process_subtitle + } + ); + $t->parsefile( file); + + +=item twig_print_outside_roots + +To be used in conjunction with the C<twig_roots> argument. When set to a true +value this will print the document outside of the C<twig_roots> elements. + + Example: my $t= XML::Twig->new( twig_roots => { title => \&number_title }, + twig_print_outside_roots => 1, + ); + $t->parsefile( file); + { my $nb; + sub number_title + { my( $twig, $title); + $nb++; + $title->prefix( "$nb "); + $title->print; + } + } + + +This example prints the document outside of the title element, calls +C<number_title> for each C<title> element, prints it, and then resumes printing +the document. The twig is built only for the C<title> elements. + +If the value is a reference to a file handle then the document outside the +C<twig_roots> elements will be output to this file handle: + + open( my $out, '>', 'out_file.xml') or die "cannot open out file.xml out_file:$!"; + my $t= XML::Twig->new( twig_roots => { title => \&number_title }, + # default output to $out + twig_print_outside_roots => $out, + ); + + { my $nb; + sub number_title + { my( $twig, $title); + $nb++; + $title->prefix( "$nb "); + $title->print( $out); # you have to print to \*OUT here + } + } + + +=item start_tag_handlers + +A hash C<{ expression => \&handler}>. Sets element handlers that are called when +the element is open (at the end of the XML::Parser C<Start> handler). The handlers +are called with 2 params: the twig and the element. The element is empty at +that point, its attributes are created though. + +You can use I<generic_attribute_condition>, I<attribute_condition>, +I<full_path>, I<partial_path>, I<tag>, I<tag_regexp>, I<_default_> and I<_all_> +to trigger the handler. + +I<string_condition> and I<regexp_condition> cannot be used as the content of +the element, and the string, have not yet been parsed when the condition is +checked. + +The main uses for those handlers are to change the tag name (you might have to +do it as soon as you find the open tag if you plan to C<flush> the twig at some +point in the element, and to create temporary attributes that will be used +when processing sub-element with C<twig_hanlders>. + +You should also use it to change tags if you use C<flush>. If you change the tag +in a regular C<twig_handler> then the start tag might already have been flushed. + +B<Note>: C<start_tag> handlers can be called outside of C<twig_roots> if this +argument is used, in this case handlers are called with the following arguments: +C<$t> (the twig), C<$tag> (the tag of the element) and C<%att> (a hash of the +attributes of the element). + +If the C<twig_print_outside_roots> argument is also used, if the last handler +called returns a C<true> value, then the start tag will be output as it +appeared in the original document, if the handler returns a C<false> value +then the start tag will B<not> be printed (so you can print a modified string +yourself for example). + +Note that you can use the L<ignore> method in C<start_tag_handlers> +(and only there). + +=item end_tag_handlers + +A hash C<{ expression => \&handler}>. Sets element handlers that are called when +the element is closed (at the end of the XML::Parser C<End> handler). The handlers +are called with 2 params: the twig and the tag of the element. + +I<twig_handlers> are called when an element is completely parsed, so why have +this redundant option? There is only one use for C<end_tag_handlers>: when using +the C<twig_roots> option, to trigger a handler for an element B<outside> the roots. +It is for example very useful to number titles in a document using nested +sections: + + my @no= (0); + my $no; + my $t= XML::Twig->new( + start_tag_handlers => + { section => sub { $no[$#no]++; $no= join '.', @no; push @no, 0; } }, + twig_roots => + { title => sub { $_[1]->prefix( $no); $_[1]->print; } }, + end_tag_handlers => { section => sub { pop @no; } }, + twig_print_outside_roots => 1 + ); + $t->parsefile( $file); + +Using the C<end_tag_handlers> argument without C<twig_roots> will result in an +error. + +=item do_not_chain_handlers + +If this option is set to a true value, then only one handler will be called for +each element, even if several satisfy the condition + +Note that the C<_all_> handler will still be called regardless + +=item ignore_elts + +This option lets you ignore elements when building the twig. This is useful +in cases where you cannot use C<twig_roots> to ignore elements, for example if +the element to ignore is a sibling of elements you are interested in. + +Example: + + my $twig= XML::Twig->new( ignore_elts => { elt => 'discard' }); + $twig->parsefile( 'doc.xml'); + +This will build the complete twig for the document, except that all C<elt> +elements (and their children) will be left out. + +The keys in the hash are triggers, limited to the same subset as +C<L<start_tag_handlers>>. The values can be C<discard>, to discard +the element, C<print>, to output the element as-is, C<string> to +store the text of the ignored element(s), including markup, in a field of +the twig: C<< $t->{twig_buffered_string} >> or a reference to a scalar, in +which case the text of the ignored element(s), including markup, will be +stored in the scalar. Any other value will be treated as C<discard>. + + +=item char_handler + +A reference to a subroutine that will be called every time C<PCDATA> is found. + +The subroutine receives the string as argument, and returns the modified string: + + # we want all strings in upper case + sub my_char_handler + { my( $text)= @_; + $text= uc( $text); + return $text; + } + +=item elt_class + +The name of a class used to store elements. this class should inherit from +C<XML::Twig::Elt> (and by default it is C<XML::Twig::Elt>). This option is used +to subclass the element class and extend it with new methods. + +This option is needed because during the parsing of the XML, elements are created +by C<XML::Twig>, without any control from the user code. + +=item keep_atts_order + +Setting this option to a true value causes the attribute hash to be tied to +a C<Tie::IxHash> object. +This means that C<Tie::IxHash> needs to be installed for this option to be +available. It also means that the hash keeps its order, so you will get +the attributes in order. This allows outputting the attributes in the same +order as they were in the original document. + +=item keep_encoding + +This is a (slightly?) evil option: if the XML document is not UTF-8 encoded and +you want to keep it that way, then setting keep_encoding will use theC<Expat> +original_string method for character, thus keeping the original encoding, as +well as the original entities in the strings. + +See the C<t/test6.t> test file to see what results you can expect from the +various encoding options. + +B<WARNING>: if the original encoding is multi-byte then attribute parsing will +be EXTREMELY unsafe under any Perl before 5.6, as it uses regular expressions +which do not deal properly with multi-byte characters. You can specify an +alternate function to parse the start tags with the C<parse_start_tag> option +(see below) + +B<WARNING>: this option is NOT used when parsing with the non-blocking parser +(C<parse_start>, C<parse_more>, parse_done methods) which you probably should +not use with XML::Twig anyway as they are totally untested! + +=item output_encoding + +This option generates an output_filter using C<Encode>, C<Text::Iconv> or +C<Unicode::Map8> and C<Unicode::Strings>, and sets the encoding in the XML +declaration. This is the easiest way to deal with encodings, if you need +more sophisticated features, look at C<output_filter> below + + +=item output_filter + +This option is used to convert the character encoding of the output document. +It is passed either a string corresponding to a predefined filter or +a subroutine reference. The filter will be called every time a document or +element is processed by the "print" functions (C<print>, C<sprint>, C<flush>). + +Pre-defined filters: + +=over 4 + +=item latin1 + +uses either C<Encode>, C<Text::Iconv> or C<Unicode::Map8> and C<Unicode::String> +or a regexp (which works only with XML::Parser 2.27), in this order, to convert +all characters to ISO-8859-15 (usually latin1 is synonym to ISO-8859-1, but +in practice it seems that ISO-8859-15, which includes the euro sign, is more +useful and probably what most people want). + +=item html + +does the same conversion as C<latin1>, plus encodes entities using +C<HTML::Entities> (oddly enough you will need to have HTML::Entities installed +for it to be available). This should only be used if the tags and attribute +names themselves are in US-ASCII, or they will be converted and the output will +not be valid XML any more + +=item safe + +converts the output to ASCII (US) only plus I<character entities> (C<&#nnn;>) +this should be used only if the tags and attribute names themselves are in +US-ASCII, or they will be converted and the output will not be valid XML any +more + +=item safe_hex + +same as C<safe> except that the character entities are in hex (C<&#xnnn;>) + +=item encode_convert ($encoding) + +Return a subref that can be used to convert utf8 strings to C<$encoding>). +Uses C<Encode>. + + my $conv = XML::Twig::encode_convert( 'latin1'); + my $t = XML::Twig->new(output_filter => $conv); + +=item iconv_convert ($encoding) + +this function is used to create a filter subroutine that will be used to +convert the characters to the target encoding using C<Text::Iconv> (which needs +to be installed, look at the documentation for the module and for the +C<iconv> library to find out which encodings are available on your system) + + my $conv = XML::Twig::iconv_convert( 'latin1'); + my $t = XML::Twig->new(output_filter => $conv); + +=item unicode_convert ($encoding) + +this function is used to create a filter subroutine that will be used to +convert the characters to the target encoding using C<Unicode::Strings> +and C<Unicode::Map8> (which need to be installed, look at the documentation +for the modules to find out which encodings are available on your system) + + my $conv = XML::Twig::unicode_convert( 'latin1'); + my $t = XML::Twig->new(output_filter => $conv); + +=back + +The C<text> and C<att> methods do not use the filter, so their +result are always in unicode. + +Those predeclared filters are based on subroutines that can be used +by themselves (as C<XML::Twig::foo>). + +=over 4 + +=item html_encode ($string) + +Use C<HTML::Entities> to encode a utf8 string + +=item safe_encode ($string) + +Use either a regexp (perl < 5.8) or C<Encode> to encode non-ascii characters +in the string in C<< &#<nnnn>; >> format + +=item safe_encode_hex ($string) + +Use either a regexp (perl < 5.8) or C<Encode> to encode non-ascii characters +in the string in C<< &#x<nnnn>; >> format + +=item regexp2latin1 ($string) + +Use a regexp to encode a utf8 string into latin 1 (ISO-8859-1). Does not +work with Perl 5.8.0! + +=back + +=item output_text_filter + +same as output_filter, except it doesn't apply to the brackets and quotes +around attribute values. This is useful for all filters that could change +the tagging, basically anything that does not just change the encoding of +the output. C<html>, C<safe> and C<safe_hex> are better used with this option. + +=item input_filter + +This option is similar to C<output_filter> except the filter is applied to +the characters before they are stored in the twig, at parsing time. + +=item remove_cdata + +Setting this option to a true value will force the twig to output CDATA +sections as regular (escaped) PCDATA + +=item parse_start_tag + +If you use the C<keep_encoding> option then this option can be used to replace +the default parsing function. You should provide a coderef (a reference to a +subroutine) as the argument, this subroutine takes the original tag (given +by XML::Parser::Expat C<original_string()> method) and returns a tag and the +attributes in a hash (or in a list attribute_name/attribute value). + +=item expand_external_ents + +When this option is used external entities (that are defined) are expanded +when the document is output using "print" functions such as C<L<print> >, +C<L<sprint> >, C<L<flush> > and C<L<xml_string> >. +Note that in the twig the entity will be stored as an element with a +tag 'C<#ENT>', the entity will not be expanded there, so you might want to +process the entities before outputting it. + +If an external entity is not available, then the parse will fail. + +A special case is when the value of this option is -1. In that case a missing +entity will not cause the parser to die, but its C<name>, C<sysid> and C<pubid> +will be stored in the twig as C<< $twig->{twig_missing_system_entities} >> +(a reference to an array of hashes { name => <name>, sysid => <sysid>, +pubid => <pubid> }). Yes, this is a bit of a hack, but it's useful in some +cases. + +=item load_DTD + +If this argument is set to a true value, C<parse> or C<parsefile> on the twig +will load the DTD information. This information can then be accessed through +the twig, in a C<DTD_handler> for example. This will load even an external DTD. + +Default and fixed values for attributes will also be filled, based on the DTD. + +Note that to do this the module will generate a temporary file in the current +directory. If this is a problem let me know and I will add an option to +specify an alternate directory. + +See L<DTD Handling> for more information + +=item DTD_handler + +Set a handler that will be called once the doctype (and the DTD) have been +loaded, with 2 arguments, the twig and the DTD. + +=item no_prolog + +Does not output a prolog (XML declaration and DTD) + +=item id + +This optional argument gives the name of an attribute that can be used as +an ID in the document. Elements whose ID is known can be accessed through +the elt_id method. id defaults to 'id'. +See C<L<BUGS> > + +=item discard_spaces + +If this optional argument is set to a true value then spaces are discarded +when they look non-significant: strings containing only spaces and at least +one line feed are discarded. This argument is set to true by default. + +The exact algorithm to drop spaces is: strings including only spaces (perl \s) +and at least one \n right before an open or close tag are dropped. + +=item discard_all_spaces + +If this argument is set to a true value, spaces are discarded more +aggressively than with C<discard_spaces>: strings not including a \n are also +dropped. This option is appropriate for data-oriented XML. + + +=item keep_spaces + +If this optional argument is set to a true value then all spaces in the +document are kept, and stored as C<PCDATA>. + +B<Warning>: adding this option can result in changes in the twig generated: +space that was previously discarded might end up in a new text element. see +the difference by calling the following code with 0 and 1 as arguments: + + perl -MXML::Twig -e'print XML::Twig->new( keep_spaces => shift)->parse( "<d> \n<e/></d>")->_dump' + + +C<keep_spaces> and C<discard_spaces> cannot be both set. + +=item discard_spaces_in + +This argument sets C<keep_spaces> to true but will cause the twig builder to +discard spaces in the elements listed. + +The syntax for using this argument is: + + XML::Twig->new( discard_spaces_in => [ 'elt1', 'elt2']); + +=item keep_spaces_in + +This argument sets C<discard_spaces> to true but will cause the twig builder to +keep spaces in the elements listed. + +The syntax for using this argument is: + + XML::Twig->new( keep_spaces_in => [ 'elt1', 'elt2']); + +B<Warning>: adding this option can result in changes in the twig generated: +space that was previously discarded might end up in a new text element. + +=item pretty_print + +Set the pretty print method, amongst 'C<none>' (default), 'C<nsgmls>', +'C<nice>', 'C<indented>', 'C<indented_c>', 'C<indented_a>', +'C<indented_close_tag>', 'C<cvs>', 'C<wrapped>', 'C<record>' and 'C<record_c>' + +pretty_print formats: + +=over 4 + +=item none + +The document is output as one ling string, with no line breaks except those +found within text elements + +=item nsgmls + +Line breaks are inserted in safe places: that is within tags, between a tag +and an attribute, between attributes and before the > at the end of a tag. + +This is quite ugly but better than C<none>, and it is very safe, the document +will still be valid (conforming to its DTD). + +This is how the SGML parser C<sgmls> splits documents, hence the name. + +=item nice + +This option inserts line breaks before any tag that does not contain text (so +element with textual content are not broken as the \n is the significant). + +B<WARNING>: this option leaves the document well-formed but might make it +invalid (not conformant to its DTD). If you have elements declared as + + <!ELEMENT foo (#PCDATA|bar)> + +then a C<foo> element including a C<bar> one will be printed as + + <foo> + <bar>bar is just pcdata</bar> + </foo> + +This is invalid, as the parser will take the line break after the C<foo> tag +as a sign that the element contains PCDATA, it will then die when it finds the +C<bar> tag. This may or may not be important for you, but be aware of it! + +=item indented + +Same as C<nice> (and with the same warning) but indents elements according to +their level + +=item indented_c + +Same as C<indented> but a little more compact: the closing tags are on the +same line as the preceding text + +=item indented_close_tag + +Same as C<indented> except that the closing tag is also indented, to line up +with the tags within the element + +=item idented_a + +This formats XML files in a line-oriented version control friendly way. +The format is described in L<http://tinyurl.com/2kwscq> (that's an Oracle +document with an insanely long URL). + +Note that to be totaly conformant to the "spec", the order of attributes +should not be changed, so if they are not already in alphabetical order +you will need to use the C<L<keep_atts_order>> option. + +=item cvs + +Same as C<L<idented_a>>. + +=item wrapped + +Same as C<indented_c> but lines are wrapped using L<Text::Wrap::wrap>. The +default length for lines is the default for C<$Text::Wrap::columns>, and can +be changed by changing that variable. + +=item record + +This is a record-oriented pretty print, that display data in records, one field +per line (which looks a LOT like C<indented>) + +=item record_c + +Stands for record compact, one record per line + +=back + + +=item empty_tags + +Set the empty tag display style ('C<normal>', 'C<html>' or 'C<expand>'). + +C<normal> outputs an empty tag 'C<< <tag/> >>', C<html> adds a space +'C<< <tag /> >>' for elements that can be empty in XHTML and C<expand> outputs +'C<< <tag></tag> >>' + +=item quote + +Set the quote character for attributes ('C<single>' or 'C<double>'). + +=item escape_gt + +By default XML::Twig does not escape the character > in its output, as it is not +mandated by the XML spec. With this option on, > will be replaced by C<>> + +=item comments + +Set the way comments are processed: 'C<drop>' (default), 'C<keep>' or +'C<process>' + +Comments processing options: + +=over 4 + +=item drop + +drops the comments, they are not read, nor printed to the output + +=item keep + +comments are loaded and will appear on the output, they are not +accessible within the twig and will not interfere with processing +though + +B<Note>: comments in the middle of a text element such as + + text  more text --> + +are kept at their original position in the text. Using ˝"print" +methods like C<print> or C<sprint> will return the comments in the +text. Using C<text> or C<field> on the other hand will not. + +Any use of C<set_pcdata> on the C<#PCDATA> element (directly or +through other methods like C<set_content>) will delete the comment(s). + +=item process + +comments are loaded in the twig and will be treated as regular elements +(their C<tag> is C<#COMMENT>) this can interfere with processing if you +expect C<< $elt->{first_child} >> to be an element but find a comment there. +Validation will not protect you from this as comments can happen anywhere. +You can use C<< $elt->first_child( 'tag') >> (which is a good habit anyway) +to get where you want. + +Consider using C<process> if you are outputting SAX events from XML::Twig. + +=back + +=item pi + +Set the way processing instructions are processed: 'C<drop>', 'C<keep>' +(default) or 'C<process>' + +Note that you can also set PI handlers in the C<twig_handlers> option: + + '?' => \&handler + '?target' => \&handler 2 + +The handlers will be called with 2 parameters, the twig and the PI element if +C<pi> is set to C<process>, and with 3, the twig, the target and the data if +C<pi> is set to C<keep>. Of course they will not be called if C<pi> is set to +C<drop>. + +If C<pi> is set to C<keep> the handler should return a string that will be used +as-is as the PI text (it should look like "C< <?target data?> >" or '' if you +want to remove the PI), + +Only one handler will be called, C<?target> or C<?> if no specific handler for +that target is available. + +=item map_xmlns + +This option is passed a hashref that maps uri's to prefixes. The prefixes in +the document will be replaced by the ones in the map. The mapped prefixes can +(actually have to) be used to trigger handlers, navigate or query the document. + +Here is an example: + + my $t= XML::Twig->new( map_xmlns => {'http://www.w3.org/2000/svg' => "svg"}, + twig_handlers => + { 'svg:circle' => sub { $_->set_att( r => 20) } }, + pretty_print => 'indented', + ) + ->parse( '<doc xmlns:gr="http://www.w3.org/2000/svg"> + <gr:circle cx="10" cy="90" r="10"/> + </doc>' + ) + ->print; + +This will output: + + <doc xmlns:svg="http://www.w3.org/2000/svg"> + <svg:circle cx="10" cy="90" r="20"/> + </doc> + +=item keep_original_prefix + +When used with C<L<map_xmlns>> this option will make C<XML::Twig> use the original +namespace prefixes when outputting a document. The mapped prefix will still be used +for triggering handlers and in navigation and query methods. + + my $t= XML::Twig->new( map_xmlns => {'http://www.w3.org/2000/svg' => "svg"}, + twig_handlers => + { 'svg:circle' => sub { $_->set_att( r => 20) } }, + keep_original_prefix => 1, + pretty_print => 'indented', + ) + ->parse( '<doc xmlns:gr="http://www.w3.org/2000/svg"> + <gr:circle cx="10" cy="90" r="10"/> + </doc>' + ) + ->print; + +This will output: + + <doc xmlns:gr="http://www.w3.org/2000/svg"> + <gr:circle cx="10" cy="90" r="20"/> + </doc> + +=item original_uri ($prefix) + +called within a handler, this will return the uri bound to the namespace prefix +in the original document. + +=item index ($arrayref or $hashref) + +This option creates lists of specific elements during the parsing of the XML. +It takes a reference to either a list of triggering expressions or to a hash +name => expression, and for each one generates the list of elements that +match the expression. The list can be accessed through the C<L<index>> method. + +example: + + # using an array ref + my $t= XML::Twig->new( index => [ 'div', 'table' ]) + ->parsefile( "foo.xml"); + my $divs= $t->index( 'div'); + my $first_div= $divs->[0]; + my $last_table= $t->index( table => -1); + + # using a hashref to name the indexes + my $t= XML::Twig->new( index => { email => 'a[@href=~/^ \s*mailto:/]'}) + ->parsefile( "foo.xml"); + my $last_emails= $t->index( email => -1); + +Note that the index is not maintained after the parsing. If elements are +deleted, renamed or otherwise hurt during processing, the index is NOT updated. +(changing the id element OTOH will update the index) + +=item att_accessors <list of attribute names> + +creates methods that give direct access to attribute: + + my $t= XML::Twig->new( att_accessors => [ 'href', 'src']) + ->parsefile( $file); + my $first_href= $t->first_elt( 'img')->src; # same as ->att( 'src') + $t->first_elt( 'img')->src( 'new_logo.png') # changes the attribute value + +=item elt_accessors + +creates methods that give direct access to the first child element (in scalar context) +or the list of elements (in list context): + +the list of accessors to create can be given 1 2 different ways: in an array, +or in a hash alias => expression + my $t= XML::Twig->new( elt_accessors => [ 'head']) + ->parsefile( $file); + my $title_text= $t->root->head->field( 'title'); + # same as $title_text= $t->root->first_child( 'head')->field( 'title'); + + my $t= XML::Twig->new( elt_accessors => { warnings => 'p[@class="warning"]', d2 => 'div[2]'}, ) + ->parsefile( $file); + my $body= $t->first_elt( 'body'); + my @warnings= $body->warnings; # same as $body->children( 'p[@class="warning"]'); + my $s2= $body->d2; # same as $body->first_child( 'div[2]') + +=item field_accessors + +creates methods that give direct access to the first child element text: + + my $t= XML::Twig->new( field_accessors => [ 'h1']) + ->parsefile( $file); + my $div_title_text= $t->first_elt( 'div')->title; + # same as $title_text= $t->first_elt( 'div')->field( 'title'); + +=item use_tidy + +set this option to use HTML::Tidy instead of HTML::TreeBuilder to convert +HTML to XML. HTML, especially real (real "crap") HTML found in the wild, +so depending on the data, one module or the other does a better job at +the conversion. Also, HTML::Tidy can be a bit difficult to install, so +XML::Twig offers both option. TIMTOWTDI + +=item output_html_doctype + +when using HTML::TreeBuilder to convert HTML, this option causes the DOCTYPE +declaration to be output, which may be important for some legacy browsers. +Without that option the DOCTYPE definition is NOT output. Also if the definition +is completely wrong (ie not easily parsable), it is not output either. + +=back + +B<Note>: I _HATE_ the Java-like name of arguments used by most XML modules. +So in pure TIMTOWTDI fashion all arguments can be written either as +C<UglyJavaLikeName> or as C<readable_perl_name>: C<twig_print_outside_roots> +or C<TwigPrintOutsideRoots> (or even C<twigPrintOutsideRoots> {shudder}). +XML::Twig normalizes them before processing them. + +=item parse ( $source) + +The C<$source> parameter should either be a string containing the whole XML +document, or it should be an open C<IO::Handle> (aka a filehandle). + +A die call is thrown if a parse error occurs. Otherwise it will return +the twig built by the parse. Use C<safe_parse> if you want the parsing +to return even when an error occurs. + +If this method is called as a class method +(C<< XML::Twig->parse( $some_xml_or_html) >>) then an XML::Twig object is +created, using the parameters except the last one (eg +C<< XML::Twig->parse( pretty_print => 'indented', $some_xml_or_html) >>) +and C<L<xparse>> is called on it. + +Note that when parsing a filehandle, the handle should NOT be open with an +encoding (ie open with C<open( my $in, '<', $filename)>. The file will be +parsed by C<expat>, so specifying the encoding actually causes problems +for the parser (as in: it can crash it, see +https://rt.cpan.org/Ticket/Display.html?id=78877). For parsing a file it +is actually recommended to use C<parsefile> on the file name, instead of +<parse> on the open file. + +=item parsestring + +This is just an alias for C<parse> for backwards compatibility. + +=item parsefile (FILE [, OPT => OPT_VALUE [...]]) + +Open C<FILE> for reading, then call C<parse> with the open handle. The file +is closed no matter how C<parse> returns. + +A C<die> call is thrown if a parse error occurs. Otherwise it will return +the twig built by the parse. Use C<safe_parsefile> if you want the parsing +to return even when an error occurs. + +=item parsefile_inplace ( $file, $optional_extension) + +Parse and update a file "in place". It does this by creating a temp file, +selecting it as the default for print() statements (and methods), then parsing +the input file. If the parsing is successful, then the temp file is +moved to replace the input file. + +If an extension is given then the original file is backed-up (the rules for +the extension are the same as the rule for the -i option in perl). + +=item parsefile_html_inplace ( $file, $optional_extension) + +Same as parsefile_inplace, except that it parses HTML instead of XML + +=item parseurl ($url $optional_user_agent) + +Gets the data from C<$url> and parse it. The data is piped to the parser in +chunks the size of the XML::Parser::Expat buffer, so memory consumption and +hopefully speed are optimal. + +For most (read "small") XML it is probably as efficient (and easier to debug) +to just C<get> the XML file and then parse it as a string. + + use XML::Twig; + use LWP::Simple; + my $twig= XML::Twig->new(); + $twig->parse( LWP::Simple::get( $URL )); + +or + + use XML::Twig; + my $twig= XML::Twig->nparse( $URL); + + +If the C<$optional_user_agent> argument is used then it is used, otherwise a +new one is created. + +=item safe_parse ( SOURCE [, OPT => OPT_VALUE [...]]) + +This method is similar to C<parse> except that it wraps the parsing in an +C<eval> block. It returns the twig on success and 0 on failure (the twig object +also contains the parsed twig). C<$@> contains the error message on failure. + +Note that the parsing still stops as soon as an error is detected, there is +no way to keep going after an error. + +=item safe_parsefile (FILE [, OPT => OPT_VALUE [...]]) + +This method is similar to C<parsefile> except that it wraps the parsing in an +C<eval> block. It returns the twig on success and 0 on failure (the twig object +also contains the parsed twig) . C<$@> contains the error message on failure + +Note that the parsing still stops as soon as an error is detected, there is +no way to keep going after an error. + +=item safe_parseurl ($url $optional_user_agent) + +Same as C<parseurl> except that it wraps the parsing in an C<eval> block. It +returns the twig on success and 0 on failure (the twig object also contains +the parsed twig) . C<$@> contains the error message on failure + +=item parse_html ($string_or_fh) + +parse an HTML string or file handle (by converting it to XML using +HTML::TreeBuilder, which needs to be available). + +This works nicely, but some information gets lost in the process: +newlines are removed, and (at least on the version I use), comments +get an extra CDATA section inside (  becomes + + +=item parsefile_html ($file) + +parse an HTML file (by converting it to XML using HTML::TreeBuilder, which +needs to be available, or HTML::Tidy if the C<use_tidy> option was used). +The file is loaded completely in memory and converted to XML before being parsed. + +this method is to be used with caution though, as it doesn't know about the +file encoding, it is usually better to use C<L<parse_html>>, which gives you +a chance to open the file with the proper encoding layer. + +=item parseurl_html ($url $optional_user_agent) + +parse an URL as html the same way C<L<parse_html>> does + +=item safe_parseurl_html ($url $optional_user_agent) + +Same as C<L<parseurl_html>>> except that it wraps the parsing in an C<eval> +block. It returns the twig on success and 0 on failure (the twig object also +contains the parsed twig) . C<$@> contains the error message on failure + +=item safe_parsefile_html ($file $optional_user_agent) + +Same as C<L<parsefile_html>>> except that it wraps the parsing in an C<eval> +block. It returns the twig on success and 0 on failure (the twig object also +contains the parsed twig) . C<$@> contains the error message on failure + +=item safe_parse_html ($string_or_fh) + +Same as C<L<parse_html>> except that it wraps the parsing in an C<eval> block. +It returns the twig on success and 0 on failure (the twig object also contains +the parsed twig) . C<$@> contains the error message on failure + +=item xparse ($thing_to_parse) + +parse the C<$thing_to_parse>, whether it is a filehandle, a string, an HTML +file, an HTML URL, an URL or a file. + +Note that this is mostly a convenience method for one-off scripts. For example +files that end in '.htm' or '.html' are parsed first as XML, and if this fails +as HTML. This is certainly not the most efficient way to do this in general. + +=item nparse ($optional_twig_options, $thing_to_parse) + +create a twig with the C<$optional_options>, and parse the C<$thing_to_parse>, +whether it is a filehandle, a string, an HTML file, an HTML URL, an URL or a +file. + +Examples: + + XML::Twig->nparse( "file.xml"); + XML::Twig->nparse( error_context => 1, "file://file.xml"); + +=item nparse_pp ($optional_twig_options, $thing_to_parse) + +same as C<L<nparse>> but also sets the C<pretty_print> option to C<indented>. + +=item nparse_e ($optional_twig_options, $thing_to_parse) + +same as C<L<nparse>> but also sets the C<error_context> option to 1. + +=item nparse_ppe ($optional_twig_options, $thing_to_parse) + +same as C<L<nparse>> but also sets the C<pretty_print> option to C<indented> +and the C<error_context> option to 1. + +=item parser + +This method returns the C<expat> object (actually the XML::Parser::Expat object) +used during parsing. It is useful for example to call XML::Parser::Expat methods +on it. To get the line of a tag for example use C<< $t->parser->current_line >>. + +=item setTwigHandlers ($handlers) + +Set the twig_handlers. C<$handlers> is a reference to a hash similar to the +one in the C<twig_handlers> option of new. All previous handlers are unset. +The method returns the reference to the previous handlers. + +=item setTwigHandler ($exp $handler) + +Set a single twig_handler for elements matching C<$exp>. C<$handler> is a +reference to a subroutine. If the handler was previously set then the reference +to the previous handler is returned. + +=item setStartTagHandlers ($handlers) + +Set the start_tag handlers. C<$handlers> is a reference to a hash similar to the +one in the C<start_tag_handlers> option of new. All previous handlers are unset. +The method returns the reference to the previous handlers. + +=item setStartTagHandler ($exp $handler) + +Set a single start_tag handlers for elements matching C<$exp>. C<$handler> is a +reference to a subroutine. If the handler was previously set then the reference +to the previous handler is returned. + +=item setEndTagHandlers ($handlers) + +Set the end_tag handlers. C<$handlers> is a reference to a hash similar to the +one in the C<end_tag_handlers> option of new. All previous handlers are unset. +The method returns the reference to the previous handlers. + +=item setEndTagHandler ($exp $handler) + +Set a single end_tag handlers for elements matching C<$exp>. C<$handler> is a +reference to a subroutine. If the handler was previously set then the +reference to the previous handler is returned. + +=item setTwigRoots ($handlers) + +Same as using the C<L<twig_roots>> option when creating the twig + +=item setCharHandler ($exp $handler) + +Set a C<char_handler> + +=item setIgnoreEltsHandler ($exp) + +Set a C<ignore_elt> handler (elements that match C<$exp> will be ignored + +=item setIgnoreEltsHandlers ($exp) + +Set all C<ignore_elt> handlers (previous handlers are replaced) + +=item dtd + +Return the dtd (an L<XML::Twig::DTD> object) of a twig + +=item xmldecl + +Return the XML declaration for the document, or a default one if it doesn't +have one + +=item doctype + +Return the doctype for the document + +=item doctype_name + +returns the doctype of the document from the doctype declaration + +=item system_id + +returns the system value of the DTD of the document from the doctype declaration + +=item public_id + +returns the public doctype of the document from the doctype declaration + +=item internal_subset + +returns the internal subset of the DTD + +=item dtd_text + +Return the DTD text + +=item dtd_print + +Print the DTD + +=item model ($tag) + +Return the model (in the DTD) for the element C<$tag> + +=item root + +Return the root element of a twig + +=item set_root ($elt) + +Set the root of a twig + +=item first_elt ($optional_condition) + +Return the first element matching C<$optional_condition> of a twig, if +no condition is given then the root is returned + +=item last_elt ($optional_condition) + +Return the last element matching C<$optional_condition> of a twig, if +no condition is given then the last element of the twig is returned + +=item elt_id ($id) + +Return the element whose C<id> attribute is $id + +=item getEltById + +Same as C<L<elt_id>> + +=item index ($index_name, $optional_index) + +If the C<$optional_index> argument is present, return the corresponding element +in the index (created using the C<index> option for C<XML::Twig->new>) + +If the argument is not present, return an arrayref to the index + +=item normalize + +merge together all consecutive pcdata elements in the document (if for example +you have turned some elements into pcdata using C<L<erase>>, this will give you +a "clean" document in which there all text elements are as long as possible). + +=item encoding + +This method returns the encoding of the XML document, as defined by the +C<encoding> attribute in the XML declaration (ie it is C<undef> if the attribute +is not defined) + +=item set_encoding + +This method sets the value of the C<encoding> attribute in the XML declaration. +Note that if the document did not have a declaration it is generated (with +an XML version of 1.0) + +=item xml_version + +This method returns the XML version, as defined by the C<version> attribute in +the XML declaration (ie it is C<undef> if the attribute is not defined) + +=item set_xml_version + +This method sets the value of the C<version> attribute in the XML declaration. +If the declaration did not exist it is created. + +=item standalone + +This method returns the value of the C<standalone> declaration for the document + +=item set_standalone + +This method sets the value of the C<standalone> attribute in the XML +declaration. Note that if the document did not have a declaration it is +generated (with an XML version of 1.0) + +=item set_output_encoding + +Set the C<encoding> "attribute" in the XML declaration + +=item set_doctype ($name, $system, $public, $internal) + +Set the doctype of the element. If an argument is C<undef> (or not present) +then its former value is retained, if a false ('' or 0) value is passed then +the former value is deleted; + +=item entity_list + +Return the entity list of a twig + +=item entity_names + +Return the list of all defined entities + +=item entity ($entity_name) + +Return the entity + +=item change_gi ($old_gi, $new_gi) + +Performs a (very fast) global change. All elements C<$old_gi> are now +C<$new_gi>. This is a bit dangerous though and should be avoided if +< possible, as the new tag might be ignored in subsequent processing. + +See C<L<BUGS> > + +=item flush ($optional_filehandle, %options) + +Flushes a twig up to (and including) the current element, then deletes +all unnecessary elements from the tree that's kept in memory. +C<flush> keeps track of which elements need to be open/closed, so if you +flush from handlers you don't have to worry about anything. Just keep +flushing the twig every time you're done with a sub-tree and it will +come out well-formed. After the whole parsing don't forget toC<flush> +one more time to print the end of the document. +The doctype and entity declarations are also printed. + +flush take an optional filehandle as an argument. + +If you use C<flush> at any point during parsing, the document will be flushed +one last time at the end of the parsing, to the proper filehandle. + +options: use the C<update_DTD> option if you have updated the (internal) DTD +and/or the entity list and you want the updated DTD to be output + +The C<pretty_print> option sets the pretty printing of the document. + + Example: $t->flush( Update_DTD => 1); + $t->flush( $filehandle, pretty_print => 'indented'); + $t->flush( \*FILE); + + +=item flush_up_to ($elt, $optional_filehandle, %options) + +Flushes up to the C<$elt> element. This allows you to keep part of the +tree in memory when you C<flush>. + +options: see flush. + +=item purge + +Does the same as a C<flush> except it does not print the twig. It just deletes +all elements that have been completely parsed so far. + +=item purge_up_to ($elt) + +Purges up to the C<$elt> element. This allows you to keep part of the tree in +memory when you C<purge>. + +=item print ($optional_filehandle, %options) + +Prints the whole document associated with the twig. To be used only AFTER the +parse. + +options: see C<flush>. + +=item print_to_file ($filename, %options) + +Prints the whole document associated with the twig to file C<$filename>. +To be used only AFTER the parse. + +options: see C<flush>. + +=item safe_print_to_file ($filename, %options) + +Prints the whole document associated with the twig to file C<$filename>. +This variant, which probably only works on *nix prints to a temp file, +then move the temp file to overwrite the original file. + +This is a bit safer when 2 processes an potentiallywrite the same file: +only the last one will succeed, but the file won't be corruted. I often +use this for cron jobs, so testing the code doesn't interfere with the +cron job running at the same time. + +options: see C<flush>. + +=item sprint + +Return the text of the whole document associated with the twig. To be used only +AFTER the parse. + +options: see C<flush>. + +=item trim + +Trim the document: gets rid of initial and trailing spaces, and replaces multiple spaces +by a single one. + +=item toSAX1 ($handler) + +Send SAX events for the twig to the SAX1 handler C<$handler> + +=item toSAX2 ($handler) + +Send SAX events for the twig to the SAX2 handler C<$handler> + +=item flush_toSAX1 ($handler) + +Same as flush, except that SAX events are sent to the SAX1 handler +C<$handler> instead of the twig being printed + +=item flush_toSAX2 ($handler) + +Same as flush, except that SAX events are sent to the SAX2 handler +C<$handler> instead of the twig being printed + +=item ignore + +This method should be called during parsing, usually in C<start_tag_handlers>. +It causes the element to be skipped during the parsing: the twig is not built +for this element, it will not be accessible during parsing or after it. The +element will not take up any memory and parsing will be faster. + +Note that this method can also be called on an element. If the element is a +parent of the current element then this element will be ignored (the twig will +not be built any more for it and what has already been built will be deleted). + +=item set_pretty_print ($style) + +Set the pretty print method, amongst 'C<none>' (default), 'C<nsgmls>', +'C<nice>', 'C<indented>', C<indented_c>, 'C<wrapped>', 'C<record>' and +'C<record_c>' + +B<WARNING:> the pretty print style is a B<GLOBAL> variable, so once set it's +applied to B<ALL> C<print>'s (and C<sprint>'s). Same goes if you use XML::Twig +with C<mod_perl> . This should not be a problem as the XML that's generated +is valid anyway, and XML processors (as well as HTML processors, including +browsers) should not care. Let me know if this is a big problem, but at the +moment the performance/cleanliness trade-off clearly favors the global +approach. + +=item set_empty_tag_style ($style) + +Set the empty tag display style ('C<normal>', 'C<html>' or 'C<expand>'). As +with C<L<set_pretty_print>> this sets a global flag. + +C<normal> outputs an empty tag 'C<< <tag/> >>', C<html> adds a space +'C<< <tag /> >>' for elements that can be empty in XHTML and C<expand> outputs +'C<< <tag></tag> >>' + +=item set_remove_cdata ($flag) + +set (or unset) the flag that forces the twig to output CDATA sections as +regular (escaped) PCDATA + +=item print_prolog ($optional_filehandle, %options) + +Prints the prolog (XML declaration + DTD + entity declarations) of a document. + +options: see C<L<flush>>. + +=item prolog ($optional_filehandle, %options) + +Return the prolog (XML declaration + DTD + entity declarations) of a document. + +options: see C<L<flush>>. + +=item finish + +Call Expat C<finish> method. +Unsets all handlers (including internal ones that set context), but expat +continues parsing to the end of the document or until it finds an error. +It should finish up a lot faster than with the handlers set. + +=item finish_print + +Stops twig processing, flush the twig and proceed to finish printing the +document as fast as possible. Use this method when modifying a document and +the modification is done. + +=item finish_now + +Stops twig processing, does not finish parsing the document (which could +actually be not well-formed after the point where C<finish_now> is called). +Execution resumes after the C<Lparse>> or C<L<parsefile>> call. The content +of the twig is what has been parsed so far (all open elements at the time +C<finish_now> is called are considered closed). + +=item set_expand_external_entities + +Same as using the C<L<expand_external_ents>> option when creating the twig + +=item set_input_filter + +Same as using the C<L<input_filter>> option when creating the twig + +=item set_keep_atts_order + +Same as using the C<L<keep_atts_order>> option when creating the twig + +=item set_keep_encoding + +Same as using the C<L<keep_encoding>> option when creating the twig + +=item escape_gt + +usually XML::Twig does not escape > in its output. Using this option +makes it replace > by > + +=item do_not_escape_gt + +reverts XML::Twig behavior to its default of not escaping > in its output. + +=item set_output_filter + +Same as using the C<L<output_filter>> option when creating the twig + +=item set_output_text_filter + +Same as using the C<L<output_text_filter>> option when creating the twig + +=item add_stylesheet ($type, @options) + +Adds an external stylesheet to an XML document. + +Supported types and options: + +=over 4 + +=item xsl + +option: the url of the stylesheet + +Example: + + $t->add_stylesheet( xsl => "xsl_style.xsl"); + +will generate the following PI at the beginning of the document: + + <?xml-stylesheet type="text/xsl" href="xsl_style.xsl"?> + +=item css + +option: the url of the stylesheet + +=item active_twig + +a class method that returns the last processed twig, so you don't necessarily +need the object to call methods on it. + +=back + +=item Methods inherited from XML::Parser::Expat + +A twig inherits all the relevant methods from XML::Parser::Expat. These +methods can only be used during the parsing phase (they will generate +a fatal error otherwise). + +Inherited methods are: + +=over 4 + +=item depth + +Returns the size of the context list. + +=item in_element + +Returns true if NAME is equal to the name of the innermost cur‐ +rently opened element. If namespace processing is being used and +you want to check against a name that may be in a namespace, then +use the generate_ns_name method to create the NAME argument. + +=item within_element + +Returns the number of times the given name appears in the context +list. If namespace processing is being used and you want to check +against a name that may be in a namespace, then use the gener‐ +ate_ns_name method to create the NAME argument. + +=item context + +Returns a list of element names that represent open elements, with +the last one being the innermost. Inside start and end tag han‐ +dlers, this will be the tag of the parent element. + +=item current_line + +Returns the line number of the current position of the parse. + +=item current_column + +Returns the column number of the current position of the parse. + +=item current_byte + +Returns the current position of the parse. + +=item position_in_context + +Returns a string that shows the current parse position. LINES +should be an integer >= 0 that represents the number of lines on +either side of the current parse line to place into the returned +string. + +=item base ([NEWBASE]) + +Returns the current value of the base for resolving relative URIs. +If NEWBASE is supplied, changes the base to that value. + +=item current_element + +Returns the name of the innermost currently opened element. Inside +start or end handlers, returns the parent of the element associated +with those tags. + +=item element_index + +Returns an integer that is the depth-first visit order of the cur‐ +rent element. This will be zero outside of the root element. For +example, this will return 1 when called from the start handler for +the root element start tag. + +=item recognized_string + +Returns the string from the document that was recognized in order +to call the current handler. For instance, when called from a start +handler, it will give us the start-tag string. The string is +encoded in UTF-8. This method doesn't return a meaningful string +inside declaration handlers. + +=item original_string + +Returns the verbatim string from the document that was recognized +in order to call the current handler. The string is in the original +document encoding. This method doesn't return a meaningful string +inside declaration handlers. + +=item xpcroak + +Concatenate onto the given message the current line number within +the XML document plus the message implied by ErrorContext. Then +croak with the formed message. + +=item xpcarp + +Concatenate onto the given message the current line number within +the XML document plus the message implied by ErrorContext. Then +carp with the formed message. + +=item xml_escape(TEXT [, CHAR [, CHAR ...]]) + +Returns TEXT with markup characters turned into character entities. +Any additional characters provided as arguments are also turned +into character references where found in TEXT. + +(this method is broken on some versions of expat/XML::Parser) + +=back + +=item path ( $optional_tag) + +Return the element context in a form similar to XPath's short +form: 'C</root/tag1/../tag>' + +=item get_xpath ( $optional_array_ref, $xpath, $optional_offset) + +Performs a C<get_xpath> on the document root (see <Elt|"Elt">) + +If the C<$optional_array_ref> argument is used the array must contain +elements. The C<$xpath> expression is applied to each element in turn +and the result is union of all results. This way a first query can be +refined in further steps. + + +=item find_nodes ( $optional_array_ref, $xpath, $optional_offset) + +same as C<get_xpath> + +=item findnodes ( $optional_array_ref, $xpath, $optional_offset) + +same as C<get_xpath> (similar to the XML::LibXML method) + +=item findvalue ( $optional_array_ref, $xpath, $optional_offset) + +Return the C<join> of all texts of the results of applying C<L<get_xpath>> +to the node (similar to the XML::LibXML method) + +=item findvalues ( $optional_array_ref, $xpath, $optional_offset) + +Return an array of all texts of the results of applying C<L<get_xpath>> +to the node + +=item subs_text ($regexp, $replace) + +subs_text does text substitution on the whole document, similar to perl's +C< s///> operator. + +=item dispose + +Useful only if you don't have C<Scalar::Util> or C<WeakRef> installed. + +Reclaims properly the memory used by an XML::Twig object. As the object has +circular references it never goes out of scope, so if you want to parse lots +of XML documents then the memory leak becomes a problem. Use +C<< $twig->dispose >> to clear this problem. + +=item att_accessors (list_of_attribute_names) + +A convenience method that creates l-valued accessors for attributes. +So C<< $twig->create_accessors( 'foo') >> will create a C<foo> method +that can be called on elements: + + $elt->foo; # equivalent to $elt->{'att'}->{'foo'}; + $elt->foo( 'bar'); # equivalent to $elt->set_att( foo => 'bar'); + +The methods are l-valued only under those perl's that support this +feature (5.6 and above) + +=item create_accessors (list_of_attribute_names) + +Same as att_accessors + +=item elt_accessors (list_of_attribute_names) + +A convenience method that creates accessors for elements. +So C<< $twig->create_accessors( 'foo') >> will create a C<foo> method +that can be called on elements: + + $elt->foo; # equivalent to $elt->first_child( 'foo'); + +=item field_accessors (list_of_attribute_names) + +A convenience method that creates accessors for element values (C<field>). +So C<< $twig->create_accessors( 'foo') >> will create a C<foo> method +that can be called on elements: + + $elt->foo; # equivalent to $elt->field( 'foo'); + +=item set_do_not_escape_amp_in_atts + +An evil method, that I only document because Test::Pod::Coverage complaints otherwise, +but really, you don't want to know about it. + +=back + +=head2 XML::Twig::Elt + +=over 4 + +=item new ($optional_tag, $optional_atts, @optional_content) + +The C<tag> is optional (but then you can't have a content ), the C<$optional_atts> +argument is a reference to a hash of attributes, the content can be just a +string or a list of strings and element. A content of 'C<#EMPTY>' creates an empty +element; + + Examples: my $elt= XML::Twig::Elt->new(); + my $elt= XML::Twig::Elt->new( para => { align => 'center' }); + my $elt= XML::Twig::Elt->new( para => { align => 'center' }, 'foo'); + my $elt= XML::Twig::Elt->new( br => '#EMPTY'); + my $elt= XML::Twig::Elt->new( 'para'); + my $elt= XML::Twig::Elt->new( para => 'this is a para'); + my $elt= XML::Twig::Elt->new( para => $elt3, 'another para'); + +The strings are not parsed, the element is not attached to any twig. + +B<WARNING>: if you rely on ID's then you will have to set the id yourself. At +this point the element does not belong to a twig yet, so the ID attribute +is not known so it won't be stored in the ID list. + +Note that C<#COMMENT>, C<#PCDATA> or C<#CDATA> are valid tag names, that will +create text elements. + +To create an element C<foo> containing a CDATA section: + + my $foo= XML::Twig::Elt->new( '#CDATA' => "content of the CDATA section") + ->wrap_in( 'foo'); + +An attribute of '#CDATA', will create the content of the element as CDATA: + + my $elt= XML::Twig::Elt->new( 'p' => { '#CDATA' => 1}, 'foo < bar'); + +creates an element + + <![CDATA[foo < bar]]></> + +=item parse ($string, %args) + +Creates an element from an XML string. The string is actually +parsed as a new twig, then the root of that twig is returned. +The arguments in C<%args> are passed to the twig. +As always if the parse fails the parser will die, so use an +eval if you want to trap syntax errors. + +As obviously the element does not exist beforehand this method has to be +called on the class: + + my $elt= parse XML::Twig::Elt( "<a> string to parse, with + <elements>, actually tons of </elements> + h</a>"); + +=item set_inner_xml ($string) + +Sets the content of the element to be the tree created from the string + +=item set_inner_html ($string) + +Sets the content of the element, after parsing the string with an HTML +parser (HTML::Parser) + +=item set_outer_xml ($string) + +Replaces the element with the tree created from the string + +=item print ($optional_filehandle, $optional_pretty_print_style) + +Prints an entire element, including the tags, optionally to a +C<$optional_filehandle>, optionally with a C<$pretty_print_style>. + +The print outputs XML data so base entities are escaped. + +=item print_to_file ($filename, %options) + +Prints the element to file C<$filename>. + +options: see C<flush>. +=item sprint ($elt, $optional_no_enclosing_tag) + +Return the xml string for an entire element, including the tags. +If the optional second argument is true then only the string inside the +element is returned (the start and end tag for $elt are not). +The text is XML-escaped: base entities (& and < in text, & < and " in +attribute values) are turned into entities. + +=item gi + +Return the gi of the element (the gi is the C<generic identifier> the tag +name in SGML parlance). + +C<tag> and C<name> are synonyms of C<gi>. + +=item tag + +Same as C<L<gi>> + +=item name + +Same as C<L<tag>> + +=item set_gi ($tag) + +Set the gi (tag) of an element + +=item set_tag ($tag) + +Set the tag (=C<L<tag>>) of an element + +=item set_name ($name) + +Set the name (=C<L<tag>>) of an element + +=item root + +Return the root of the twig in which the element is contained. + +=item twig + +Return the twig containing the element. + +=item parent ($optional_condition) + +Return the parent of the element, or the first ancestor matching the +C<$optional_condition> + +=item first_child ($optional_condition) + +Return the first child of the element, or the first child matching the +C<$optional_condition> + +=item has_child ($optional_condition) + +Return the first child of the element, or the first child matching the +C<$optional_condition> (same as L<first_child>) + +=item has_children ($optional_condition) + +Return the first child of the element, or the first child matching the +C<$optional_condition> (same as L<first_child>) + + +=item first_child_text ($optional_condition) + +Return the text of the first child of the element, or the first child + matching the C<$optional_condition> +If there is no first_child then returns ''. This avoids getting the +child, checking for its existence then getting the text for trivial cases. + +Similar methods are available for the other navigation methods: + +=over 4 + +=item last_child_text + +=item prev_sibling_text + +=item next_sibling_text + +=item prev_elt_text + +=item next_elt_text + +=item child_text + +=item parent_text + +=back + +All this methods also exist in "trimmed" variant: + +=over 4 + +=item first_child_trimmed_text + +=item last_child_trimmed_text + +=item prev_sibling_trimmed_text + +=item next_sibling_trimmed_text + +=item prev_elt_trimmed_text + +=item next_elt_trimmed_text + +=item child_trimmed_text + +=item parent_trimmed_text + +=back + +=item field ($condition) + +Same method as C<first_child_text> with a different name + +=item fields ($condition_list) + +Return the list of field (text of first child matching the conditions), +missing fields are returned as the empty string. + +Same method as C<first_child_text> with a different name + +=item trimmed_field ($optional_condition) + +Same method as C<first_child_trimmed_text> with a different name + +=item set_field ($condition, $optional_atts, @list_of_elt_and_strings) + +Set the content of the first child of the element that matches +C<$condition>, the rest of the arguments is the same as for C<L<set_content>> + +If no child matches C<$condition> _and_ if C<$condition> is a valid +XML element name, then a new element by that name is created and +inserted as the last child. + +=item first_child_matches ($optional_condition) + +Return the element if the first child of the element (if it exists) passes +the C<$optional_condition> C<undef> otherwise + + if( $elt->first_child_matches( 'title')) ... + +is equivalent to + + if( $elt->{first_child} && $elt->{first_child}->passes( 'title')) + +C<first_child_is> is an other name for this method + +Similar methods are available for the other navigation methods: + +=over 4 + +=item last_child_matches + +=item prev_sibling_matches + +=item next_sibling_matches + +=item prev_elt_matches + +=item next_elt_matches + +=item child_matches + +=item parent_matches + +=back + +=item is_first_child ($optional_condition) + +returns true (the element) if the element is the first child of its parent +(optionally that satisfies the C<$optional_condition>) + +=item is_last_child ($optional_condition) + +returns true (the element) if the element is the last child of its parent +(optionally that satisfies the C<$optional_condition>) + +=item prev_sibling ($optional_condition) + +Return the previous sibling of the element, or the previous sibling matching +C<$optional_condition> + +=item next_sibling ($optional_condition) + +Return the next sibling of the element, or the first one matching +C<$optional_condition>. + +=item next_elt ($optional_elt, $optional_condition) + +Return the next elt (optionally matching C<$optional_condition>) of the element. This +is defined as the next element which opens after the current element opens. +Which usually means the first child of the element. +Counter-intuitive as it might look this allows you to loop through the +whole document by starting from the root. + +The C<$optional_elt> is the root of a subtree. When the C<next_elt> is out of the +subtree then the method returns undef. You can then walk a sub-tree with: + + my $elt= $subtree_root; + while( $elt= $elt->next_elt( $subtree_root)) + { # insert processing code here + } + +=item prev_elt ($optional_condition) + +Return the previous elt (optionally matching C<$optional_condition>) of the +element. This is the first element which opens before the current one. +It is usually either the last descendant of the previous sibling or +simply the parent + +=item next_n_elt ($offset, $optional_condition) + +Return the C<$offset>-th element that matches the C<$optional_condition> + +=item following_elt + +Return the following element (as per the XPath following axis) + +=item preceding_elt + +Return the preceding element (as per the XPath preceding axis) + +=item following_elts + +Return the list of following elements (as per the XPath following axis) + +=item preceding_elts + +Return the list of preceding elements (as per the XPath preceding axis) + +=item children ($optional_condition) + +Return the list of children (optionally which matches C<$optional_condition>) of +the element. The list is in document order. + +=item children_count ($optional_condition) + +Return the number of children of the element (optionally which matches +C<$optional_condition>) + +=item children_text ($optional_condition) + +In array context, returns an array containing the text of children of the +element (optionally which matches C<$optional_condition>) + +In scalar context, returns the concatenation of the text of children of +the element + +=item children_trimmed_text ($optional_condition) + +In array context, returns an array containing the trimmed text of children +of the element (optionally which matches C<$optional_condition>) + +In scalar context, returns the concatenation of the trimmed text of children of +the element + + +=item children_copy ($optional_condition) + +Return a list of elements that are copies of the children of the element, +optionally which matches C<$optional_condition> + +=item descendants ($optional_condition) + +Return the list of all descendants (optionally which matches +C<$optional_condition>) of the element. This is the equivalent of the +C<getElementsByTagName> of the DOM (by the way, if you are really a DOM +addict, you can use C<getElementsByTagName> instead) + +=item getElementsByTagName ($optional_condition) + +Same as C<L<descendants>> + +=item find_by_tag_name ($optional_condition) + +Same as C<L<descendants>> + +=item descendants_or_self ($optional_condition) + +Same as C<L<descendants>> except that the element itself is included in the list +if it matches the C<$optional_condition> + +=item first_descendant ($optional_condition) + +Return the first descendant of the element that matches the condition + +=item last_descendant ($optional_condition) + +Return the last descendant of the element that matches the condition + +=item ancestors ($optional_condition) + +Return the list of ancestors (optionally matching C<$optional_condition>) of the +element. The list is ordered from the innermost ancestor to the outermost one + +NOTE: the element itself is not part of the list, in order to include it +you will have to use ancestors_or_self + +=item ancestors_or_self ($optional_condition) + +Return the list of ancestors (optionally matching C<$optional_condition>) of the +element, including the element (if it matches the condition>). +The list is ordered from the innermost ancestor to the outermost one + +=item passes ($condition) + +Return the element if it passes the C<$condition> + +=item att ($att) + +Return the value of attribute C<$att> or C<undef> + +=item latt ($att) + +Return the value of attribute C<$att> or C<undef> + +this method is an lvalue, so you can do C<< $elt->latt( 'foo')= 'bar' >> or C<< $elt->latt( 'foo')++; >> + +=item set_att ($att, $att_value) + +Set the attribute of the element to the given value + +You can actually set several attributes this way: + + $elt->set_att( att1 => "val1", att2 => "val2"); + +=item del_att ($att) + +Delete the attribute for the element + +You can actually delete several attributes at once: + + $elt->del_att( 'att1', 'att2', 'att3'); + +=item att_exists ($att) + +Returns true if the attribute C<$att> exists for the element, false +otherwise + +=item cut + +Cut the element from the tree. The element still exists, it can be copied +or pasted somewhere else, it is just not attached to the tree anymore. + +Note that the "old" links to the parent, previous and next siblings can +still be accessed using the former_* methods + +=item former_next_sibling + +Returns the former next sibling of a cut node (or undef if the node has not been cut) + +This makes it easier to write loops where you cut elements: + + my $child= $parent->first_child( 'achild'); + while( $child->{'att'}->{'cut'}) + { $child->cut; $child= ($child->{former} && $child->{former}->{next_sibling}); } + +=item former_prev_sibling + +Returns the former previous sibling of a cut node (or undef if the node has not been cut) + +=item former_parent + +Returns the former parent of a cut node (or undef if the node has not been cut) + +=item cut_children ($optional_condition) + +Cut all the children of the element (or all of those which satisfy the +C<$optional_condition>). + +Return the list of children + +=item cut_descendants ($optional_condition) + +Cut all the descendants of the element (or all of those which satisfy the +C<$optional_condition>). + +Return the list of descendants + +=item copy ($elt) + +Return a copy of the element. The copy is a "deep" copy: all sub-elements of +the element are duplicated. + +=item paste ($optional_position, $ref) + +Paste a (previously C<cut> or newly generated) element. Die if the element +already belongs to a tree. + +Note that the calling element is pasted: + + $child->paste( first_child => $existing_parent); + $new_sibling->paste( after => $this_sibling_is_already_in_the_tree); + +or + + my $new_elt= XML::Twig::Elt->new( tag => $content); + $new_elt->paste( $position => $existing_elt); + +Example: + + my $t= XML::Twig->new->parse( 'doc.xml') + my $toc= $t->root->new( 'toc'); + $toc->paste( $t->root); # $toc is pasted as first child of the root + foreach my $title ($t->findnodes( '/doc/section/title')) + { my $title_toc= $title->copy; + # paste $title_toc as the last child of toc + $title_toc->paste( last_child => $toc) + } + +Position options: + +=over 4 + +=item first_child (default) + +The element is pasted as the first child of C<$ref> + +=item last_child + +The element is pasted as the last child of C<$ref> + +=item before + +The element is pasted before C<$ref>, as its previous sibling. + +=item after + +The element is pasted after C<$ref>, as its next sibling. + +=item within + +In this case an extra argument, C<$offset>, should be supplied. The element +will be pasted in the reference element (or in its first text child) at the +given offset. To achieve this the reference element will be split at the +offset. + +=back + +Note that you can call directly the underlying method: + +=over 4 + +=item paste_before + +=item paste_after + +=item paste_first_child + +=item paste_last_child + +=item paste_within + +=back + +=item move ($optional_position, $ref) + +Move an element in the tree. +This is just a C<cut> then a C<paste>. The syntax is the same as C<paste>. + +=item replace ($ref) + +Replaces an element in the tree. Sometimes it is just not possible toC<cut> +an element then C<paste> another in its place, so C<replace> comes in handy. +The calling element replaces C<$ref>. + +=item replace_with (@elts) + +Replaces the calling element with one or more elements + +=item delete + +Cut the element and frees the memory. + +=item prefix ($text, $optional_option) + +Add a prefix to an element. If the element is a C<PCDATA> element the text +is added to the pcdata, if the elements first child is a C<PCDATA> then the +text is added to it's pcdata, otherwise a new C<PCDATA> element is created +and pasted as the first child of the element. + +If the option is C<asis> then the prefix is added asis: it is created in +a separate C<PCDATA> element with an C<asis> property. You can then write: + + $elt1->prefix( '', 'asis'); + +to create a C<< >> in the output of C<print>. + +=item suffix ($text, $optional_option) + +Add a suffix to an element. If the element is a C<PCDATA> element the text +is added to the pcdata, if the elements last child is a C<PCDATA> then the +text is added to it's pcdata, otherwise a new PCDATA element is created +and pasted as the last child of the element. + +If the option is C<asis> then the suffix is added asis: it is created in +a separate C<PCDATA> element with an C<asis> property. You can then write: + + $elt2->suffix( '', 'asis'); + +=item trim + +Trim the element in-place: spaces at the beginning and at the end of the element +are discarded and multiple spaces within the element (or its descendants) are +replaced by a single space. + +Note that in some cases you can still end up with multiple spaces, if they are +split between several elements: + + <doc> text hah! yep</doc> + +gets trimmed to + + <doc>text hah! yep</doc> + +This is somewhere in between a bug and a feature. + +=item normalize + +merge together all consecutive pcdata elements in the element (if for example +you have turned some elements into pcdata using C<L<erase>>, this will give you +a "clean" element in which there all text fragments are as long as possible). + + +=item simplify (%options) + +Return a data structure suspiciously similar to XML::Simple's. Options are +identical to XMLin options, see XML::Simple doc for more details (or use +DATA::dumper or YAML to dump the data structure) + +B<Note>: there is no magic here, if you write +C<< $twig->parsefile( $file )->simplify(); >> then it will load the entire +document in memory. I am afraid you will have to put some work into it to +get just the bits you want and discard the rest. Look at the synopsis or +the XML::Twig 101 section at the top of the docs for more information. + +=over 4 + +=item content_key + +=item forcearray + +=item keyattr + +=item noattr + +=item normalize_space + +aka normalise_space + +=item variables (%var_hash) + +%var_hash is a hash { name => value } + +This option allows variables in the XML to be expanded when the file is read. (there is no facility for putting the variable names back if you regenerate XML using XMLout). + +A 'variable' is any text of the form ${name} (or $name) which occurs in an attribute value or in the text content of an element. If 'name' matches a key in the supplied hashref, ${name} will be replaced with the corresponding value from the hashref. If no matching key is found, the variable will not be replaced. + +=item var_att ($attribute_name) + +This option gives the name of an attribute that will be used to create +variables in the XML: + + <dirs> + <dir name="prefix">/usr/local</dir> + <dir name="exec_prefix">$prefix/bin</dir> + </dirs> + +use C<< var => 'name' >> to get $prefix replaced by /usr/local in the +generated data structure + +By default variables are captured by the following regexp: /$(\w+)/ + +=item var_regexp (regexp) + +This option changes the regexp used to capture variables. The variable +name should be in $1 + +=item group_tags { grouping tag => grouped tag, grouping tag 2 => grouped tag 2...} + +Option used to simplify the structure: elements listed will not be used. +Their children will be, they will be considered children of the element +parent. + +If the element is: + + <config host="laptop.xmltwig.org"> + <server>localhost</server> + <dirs> + <dir name="base">/home/mrodrigu/standards</dir> + <dir name="tools">$base/tools</dir> + </dirs> + <templates> + <template name="std_def">std_def.templ</template> + <template name="dummy">dummy</template> + </templates> + </config> + +Then calling simplify with C<< group_tags => { dirs => 'dir', +templates => 'template'} >> +makes the data structure be exactly as if the start and end tags for C<dirs> and +C<templates> were not there. + +A YAML dump of the structure + + base: '/home/mrodrigu/standards' + host: laptop.xmltwig.org + server: localhost + template: + - std_def.templ + - dummy.templ + tools: '$base/tools' + + +=back + +=item split_at ($offset) + +Split a text (C<PCDATA> or C<CDATA>) element in 2 at C<$offset>, the original +element now holds the first part of the string and a new element holds the +right part. The new element is returned + +If the element is not a text element then the first text child of the element +is split + +=item split ( $optional_regexp, $tag1, $atts1, $tag2, $atts2...) + +Split the text descendants of an element in place, the text is split using +the C<$regexp>, if the regexp includes () then the matched separators will be +wrapped in elements. C<$1> is wrapped in $tag1, with attributes C<$atts1> if +C<$atts1> is given (as a hashref), C<$2> is wrapped in $tag2... + +if $elt is C<< tati tata tutu tati titi tata tati tata >> + + $elt->split( qr/(ta)ti/, 'foo', {type => 'toto'} ) + +will change $elt to + + <foo type="toto">ta</foo> tata tutu <foo type="toto">ta</foo> + titi tata <foo type="toto">ta</foo> tata + +The regexp can be passed either as a string or as C<qr//> (perl 5.005 and +later), it defaults to \s+ just as the C<split> built-in (but this would be +quite a useless behaviour without the C<$optional_tag> parameter) + +C<$optional_tag> defaults to PCDATA or CDATA, depending on the initial element +type + +The list of descendants is returned (including un-touched original elements +and newly created ones) + +=item mark ( $regexp, $optional_tag, $optional_attribute_ref) + +This method behaves exactly as L<split>, except only the newly created +elements are returned + +=item wrap_children ( $regexp_string, $tag, $optional_attribute_hashref) + +Wrap the children of the element that match the regexp in an element C<$tag>. +If $optional_attribute_hashref is passed then the new element will +have these attributes. + +The $regexp_string includes tags, within pointy brackets, as in +C<< <title><para>+ >> and the usual Perl modifiers (+*?...). +Tags can be further qualified with attributes: +C<< <para type="warning" classif="cosmic_secret">+ >>. The values +for attributes should be xml-escaped: C<< <candy type="M&Ms">* >> +(C<E<lt>>, C<&> B<C<E<gt>>> and C<"> should be escaped). + +Note that elements might get extra C<id> attributes in the process. See L<add_id>. +Use L<strip_att> to remove unwanted id's. + +Here is an example: + +If the element C<$elt> has the following content: + + <elt> + para 1 + <l_l1_1>list 1 item 1 para 1</l_l1_1> + <l_l1>list 1 item 1 para 2</l_l1> + <l_l1_n>list 1 item 2 para 1 (only para)</l_l1_n> + <l_l1_n>list 1 item 3 para 1</l_l1_n> + <l_l1>list 1 item 3 para 2</l_l1> + <l_l1>list 1 item 3 para 3</l_l1> + <l_l1_1>list 2 item 1 para 1</l_l1_1> + <l_l1>list 2 item 1 para 2</l_l1> + <l_l1_n>list 2 item 2 para 1 (only para)</l_l1_n> + <l_l1_n>list 2 item 3 para 1</l_l1_n> + <l_l1>list 2 item 3 para 2</l_l1> + <l_l1>list 2 item 3 para 3</l_l1> + </elt> + +Then the code + + $elt->wrap_children( q{<l_l1_1><l_l1>*} , li => { type => "ul1" }); + $elt->wrap_children( q{<l_l1_n><l_l1>*} , li => { type => "ul" }); + + $elt->wrap_children( q{<li type="ul1"><li type="ul">+}, "ul"); + $elt->strip_att( 'id'); + $elt->strip_att( 'type'); + $elt->print; + +will output: + + <elt> + para 1 + <ul> + <li> + <l_l1_1>list 1 item 1 para 1</l_l1_1> + <l_l1>list 1 item 1 para 2</l_l1> + </li> + <li> + <l_l1_n>list 1 item 2 para 1 (only para)</l_l1_n> + </li> + <li> + <l_l1_n>list 1 item 3 para 1</l_l1_n> + <l_l1>list 1 item 3 para 2</l_l1> + <l_l1>list 1 item 3 para 3</l_l1> + </li> + </ul> + <ul> + <li> + <l_l1_1>list 2 item 1 para 1</l_l1_1> + <l_l1>list 2 item 1 para 2</l_l1> + </li> + <li> + <l_l1_n>list 2 item 2 para 1 (only para)</l_l1_n> + </li> + <li> + <l_l1_n>list 2 item 3 para 1</l_l1_n> + <l_l1>list 2 item 3 para 2</l_l1> + <l_l1>list 2 item 3 para 3</l_l1> + </li> + </ul> + </elt> + +=item subs_text ($regexp, $replace) + +subs_text does text substitution, similar to perl's C< s///> operator. + +C<$regexp> must be a perl regexp, created with the C<qr> operator. + +C<$replace> can include C<$1, $2>... from the C<$regexp>. It can also be +used to create element and entities, by using +C<< &elt( tag => { att => val }, text) >> (similar syntax as C<L<new>>) and +C<< &ent( name) >>. + +Here is a rather complex example: + + $elt->subs_text( qr{(?<!do not )link to (http://([^\s,]*))}, + 'see &elt( a =>{ href => $1 }, $2)' + ); + +This will replace text like I<link to http://www.xmltwig.org> by +I<< see <a href="www.xmltwig.org">www.xmltwig.org</a> >>, but not +I<do not link to...> + +Generating entities (here replacing spaces with ): + + $elt->subs_text( qr{ }, '&ent( " ")'); + +or, using a variable: + + my $ent=" "; + $elt->subs_text( qr{ }, "&ent( '$ent')"); + +Note that the substitution is always global, as in using the C<g> modifier +in a perl substitution, and that it is performed on all text descendants +of the element. + +B<Bug>: in the C<$regexp>, you can only use C<\1>, C<\2>... if the replacement +expression does not include elements or attributes. eg + + $t->subs_text( qr/((t[aiou])\2)/, '$2'); # ok, replaces toto, tata, titi, tutu by to, ta, ti, tu + $t->subs_text( qr/((t[aiou])\2)/, '&elt(p => $1)' ); # NOK, does not find toto... + +=item add_id ($optional_coderef) + +Add an id to the element. + +The id is an attribute, C<id> by default, see the C<id> option for XML::Twig +C<new> to change it. Use an id starting with C<#> to get an id that's not +output by L<print>, L<flush> or L<sprint>, yet that allows you to use the +L<elt_id> method to get the element easily. + +If the element already has an id, no new id is generated. + +By default the method create an id of the form C<< twig_id_<nnnn> >>, +where C<< <nnnn> >> is a number, incremented each time the method is called +successfully. + +=item set_id_seed ($prefix) + +by default the id generated by C<L<add_id>> is C<< twig_id_<nnnn> >>, +C<set_id_seed> changes the prefix to C<$prefix> and resets the number +to 1 + +=item strip_att ($att) + +Remove the attribute C<$att> from all descendants of the element (including +the element) + +Return the element + +=item change_att_name ($old_name, $new_name) + +Change the name of the attribute from C<$old_name> to C<$new_name>. If there is no +attribute C<$old_name> nothing happens. + +=item lc_attnames + +Lower cases the name all the attributes of the element. + +=item sort_children_on_value( %options) + +Sort the children of the element in place according to their text. +All children are sorted. + +Return the element, with its children sorted. + + +C<%options> are + + type : numeric | alpha (default: alpha) + order : normal | reverse (default: normal) + +Return the element, with its children sorted + + +=item sort_children_on_att ($att, %options) + +Sort the children of the element in place according to attribute C<$att>. +C<%options> are the same as for C<sort_children_on_value> + +Return the element. + + +=item sort_children_on_field ($tag, %options) + +Sort the children of the element in place, according to the field C<$tag> (the +text of the first child of the child with this tag). C<%options> are the same +as for C<sort_children_on_value>. + +Return the element, with its children sorted + + +=item sort_children( $get_key, %options) + +Sort the children of the element in place. The C<$get_key> argument is +a reference to a function that returns the sort key when passed an element. + +For example: + + $elt->sort_children( sub { $_[0]->{'att'}->{"nb"} + $_[0]->text }, + type => 'numeric', order => 'reverse' + ); + +=item field_to_att ($cond, $att) + +Turn the text of the first sub-element matched by C<$cond> into the value of +attribute C<$att> of the element. If C<$att> is omitted then C<$cond> is used +as the name of the attribute, which makes sense only if C<$cond> is a valid +element (and attribute) name. + +The sub-element is then cut. + +=item att_to_field ($att, $tag) + +Take the value of attribute C<$att> and create a sub-element C<$tag> as first +child of the element. If C<$tag> is omitted then C<$att> is used as the name of +the sub-element. + + +=item get_xpath ($xpath, $optional_offset) + +Return a list of elements satisfying the C<$xpath>. C<$xpath> is an XPATH-like +expression. + +A subset of the XPATH abbreviated syntax is covered: + + tag + tag[1] (or any other positive number) + tag[last()] + tag[@att] (the attribute exists for the element) + tag[@att="val"] + tag[@att=~ /regexp/] + tag[att1="val1" and att2="val2"] + tag[att1="val1" or att2="val2"] + tag[string()="toto"] (returns tag elements which text (as per the text method) + is toto) + tag[string()=~/regexp/] (returns tag elements which text (as per the text + method) matches regexp) + expressions can start with / (search starts at the document root) + expressions can start with . (search starts at the current element) + // can be used to get all descendants instead of just direct children + * matches any tag + +So the following examples from the +F<XPath recommendationL<http://www.w3.org/TR/xpath.html#path-abbrev>> work: + + para selects the para element children of the context node + * selects all element children of the context node + para[1] selects the first para child of the context node + para[last()] selects the last para child of the context node + */para selects all para grandchildren of the context node + /doc/chapter[5]/section[2] selects the second section of the fifth chapter + of the doc + chapter//para selects the para element descendants of the chapter element + children of the context node + //para selects all the para descendants of the document root and thus selects + all para elements in the same document as the context node + //olist/item selects all the item elements in the same document as the + context node that have an olist parent + .//para selects the para element descendants of the context node + .. selects the parent of the context node + para[@type="warning"] selects all para children of the context node that have + a type attribute with value warning + employee[@secretary and @assistant] selects all the employee children of the + context node that have both a secretary attribute and an assistant + attribute + + +The elements will be returned in the document order. + +If C<$optional_offset> is used then only one element will be returned, the one +with the appropriate offset in the list, starting at 0 + +Quoting and interpolating variables can be a pain when the Perl syntax and the +XPATH syntax collide, so use alternate quoting mechanisms like q or qq +(I like q{} and qq{} myself). + +Here are some more examples to get you started: + + my $p1= "p1"; + my $p2= "p2"; + my @res= $t->get_xpath( qq{p[string( "$p1") or string( "$p2")]}); + + my $a= "a1"; + my @res= $t->get_xpath( qq{//*[@att="$a"]}); + + my $val= "a1"; + my $exp= qq{//p[ \@att='$val']}; # you need to use \@ or you will get a warning + my @res= $t->get_xpath( $exp); + +Note that the only supported regexps delimiters are / and that you must +backslash all / in regexps AND in regular strings. + +XML::Twig does not provide natively full XPATH support, but you can use +C<L<XML::Twig::XPath>> to get C<findnodes> to use C<XML::XPath> as the +XPath engine, with full coverage of the spec. + +C<L<XML::Twig::XPath>> to get C<findnodes> to use C<XML::XPath> as the +XPath engine, with full coverage of the spec. + +=item find_nodes + +same asC<get_xpath> + +=item findnodes + +same as C<get_xpath> + + +=item text @optional_options + +Return a string consisting of all the C<PCDATA> and C<CDATA> in an element, +without any tags. The text is not XML-escaped: base entities such as C<&> +and C<< < >> are not escaped. + +The 'C<no_recurse>' option will only return the text of the element, not +of any included sub-elements (same as C<L<text_only>>). + +=item text_only + +Same as C<L<text>> except that the text returned doesn't include +the text of sub-elements. + +=item trimmed_text + +Same as C<text> except that the text is trimmed: leading and trailing spaces +are discarded, consecutive spaces are collapsed + +=item set_text ($string) + +Set the text for the element: if the element is a C<PCDATA>, just set its +text, otherwise cut all the children of the element and create a single +C<PCDATA> child for it, which holds the text. + +=item merge ($elt2) + +Move the content of C<$elt2> within the element + +=item insert ($tag1, [$optional_atts1], $tag2, [$optional_atts2],...) + +For each tag in the list inserts an element C<$tag> as the only child of the +element. The element gets the optional attributes inC<< $optional_atts<n>. >> +All children of the element are set as children of the new element. +The upper level element is returned. + + $p->insert( table => { border=> 1}, 'tr', 'td') + +put C<$p> in a table with a visible border, a single C<tr> and a single C<td> +and return the C<table> element: + + <table border="1"><tr><td>original content of p</td></tr></table> + +=item wrap_in (@tag) + +Wrap elements in C<@tag> as the successive ancestors of the element, returns the +new element. +C<< $elt->wrap_in( 'td', 'tr', 'table') >> wraps the element as a single cell in a +table for example. + +Optionally each tag can be followed by a hashref of attributes, that will be +set on the wrapping element: + + $elt->wrap_in( p => { class => "advisory" }, div => { class => "intro", id => "div_intro" }); + +=item insert_new_elt ($opt_position, $tag, $opt_atts_hashref, @opt_content) + +Combines a C<L<new> > and a C<L<paste> >: creates a new element using +C<$tag>, C<$opt_atts_hashref >and C<@opt_content> which are arguments similar +to those for C<new>, then paste it, using C<$opt_position> or C<'first_child'>, +relative to C<$elt>. + +Return the newly created element + +=item erase + +Erase the element: the element is deleted and all of its children are +pasted in its place. + +=item set_content ( $optional_atts, @list_of_elt_and_strings) + ( $optional_atts, '#EMPTY') + +Set the content for the element, from a list of strings and +elements. Cuts all the element children, then pastes the list +elements as the children. This method will create a C<PCDATA> element +for any strings in the list. + +The C<$optional_atts> argument is the ref of a hash of attributes. If this +argument is used then the previous attributes are deleted, otherwise they +are left untouched. + +B<WARNING>: if you rely on ID's then you will have to set the id yourself. At +this point the element does not belong to a twig yet, so the ID attribute +is not known so it won't be stored in the ID list. + +A content of 'C<#EMPTY>' creates an empty element; + +=item namespace ($optional_prefix) + +Return the URI of the namespace that C<$optional_prefix> or the element name +belongs to. If the name doesn't belong to any namespace, C<undef> is returned. + +=item local_name + +Return the local name (without the prefix) for the element + +=item ns_prefix + +Return the namespace prefix for the element + +=item current_ns_prefixes + +Return a list of namespace prefixes valid for the element. The order of the +prefixes in the list has no meaning. If the default namespace is currently +bound, '' appears in the list. + + +=item inherit_att ($att, @optional_tag_list) + +Return the value of an attribute inherited from parent tags. The value +returned is found by looking for the attribute in the element then in turn +in each of its ancestors. If the C<@optional_tag_list> is supplied only those +ancestors whose tag is in the list will be checked. + +=item all_children_are ($optional_condition) + +return 1 if all children of the element pass the C<$optional_condition>, +0 otherwise + +=item level ($optional_condition) + +Return the depth of the element in the twig (root is 0). +If C<$optional_condition> is given then only ancestors that match the condition are +counted. + +B<WARNING>: in a tree created using the C<twig_roots> option this will not return +the level in the document tree, level 0 will be the document root, level 1 +will be the C<twig_roots> elements. During the parsing (in a C<twig_handler>) +you can use the C<depth> method on the twig object to get the real parsing depth. + +=item in ($potential_parent) + +Return true if the element is in the potential_parent (C<$potential_parent> is +an element) + +=item in_context ($cond, $optional_level) + +Return true if the element is included in an element which passes C<$cond> +optionally within C<$optional_level> levels. The returned value is the +including element. + +=item pcdata + +Return the text of a C<PCDATA> element or C<undef> if the element is not +C<PCDATA>. + +=item pcdata_xml_string + +Return the text of a C<PCDATA> element or undef if the element is not C<PCDATA>. +The text is "XML-escaped" ('&' and '<' are replaced by '&' and '<') + +=item set_pcdata ($text) + +Set the text of a C<PCDATA> element. This method does not check that the element is +indeed a C<PCDATA> so usually you should use C<L<set_text>> instead. + +=item append_pcdata ($text) + +Add the text at the end of a C<PCDATA> element. + +=item is_cdata + +Return 1 if the element is a C<CDATA> element, returns 0 otherwise. + +=item is_text + +Return 1 if the element is a C<CDATA> or C<PCDATA> element, returns 0 otherwise. + +=item cdata + +Return the text of a C<CDATA> element or C<undef> if the element is not +C<CDATA>. + +=item cdata_string + +Return the XML string of a C<CDATA> element, including the opening and +closing markers. + +=item set_cdata ($text) + +Set the text of a C<CDATA> element. + +=item append_cdata ($text) + +Add the text at the end of a C<CDATA> element. + +=item remove_cdata + +Turns all C<CDATA> sections in the element into regular C<PCDATA> elements. This is useful +when converting XML to HTML, as browsers do not support CDATA sections. + +=item extra_data + +Return the extra_data (comments and PI's) attached to an element + +=item set_extra_data ($extra_data) + +Set the extra_data (comments and PI's) attached to an element + +=item append_extra_data ($extra_data) + +Append extra_data to the existing extra_data before the element (if no +previous extra_data exists then it is created) + +=item set_asis + +Set a property of the element that causes it to be output without being XML +escaped by the print functions: if it contains C<< a > it will be output +as such and not as C<< a >. This can be useful to create text elements +that will be output as markup. Note that all C<PCDATA> descendants of the +element are also marked as having the property (they are the ones that are +actually impacted by the change). + +If the element is a C<CDATA> element it will also be output asis, without the +C<CDATA> markers. The same goes for any C<CDATA> descendant of the element + +=item set_not_asis + +Unsets the C<asis> property for the element and its text descendants. + +=item is_asis + +Return the C<asis> property status of the element ( 1 or C<undef>) + +=item closed + +Return true if the element has been closed. Might be useful if you are +somewhere in the tree, during the parse, and have no idea whether a parent +element is completely loaded or not. + +=item get_type + +Return the type of the element: 'C<#ELT>' for "real" elements, or 'C<#PCDATA>', +'C<#CDATA>', 'C<#COMMENT>', 'C<#ENT>', 'C<#PI>' + +=item is_elt + +Return the tag if the element is a "real" element, or 0 if it is C<PCDATA>, +C<CDATA>... + +=item contains_only_text + +Return 1 if the element does not contain any other "real" element + +=item contains_only ($exp) + +Return the list of children if all children of the element match +the expression C<$exp> + + if( $para->contains_only( 'tt')) { ... } + +=item contains_a_single ($exp) + +If the element contains a single child that matches the expression C<$exp> +returns that element. Otherwise returns 0. + +=item is_field + +same as C<contains_only_text> + +=item is_pcdata + +Return 1 if the element is a C<PCDATA> element, returns 0 otherwise. + +=item is_ent + +Return 1 if the element is an entity (an unexpanded entity) element, +return 0 otherwise. + +=item is_empty + +Return 1 if the element is empty, 0 otherwise + +=item set_empty + +Flags the element as empty. No further check is made, so if the element +is actually not empty the output will be messed. The only effect of this +method is that the output will be C<< <tag att="value""/> >>. + +=item set_not_empty + +Flags the element as not empty. if it is actually empty then the element will +be output as C<< <tag att="value""></tag> >> + +=item is_pi + +Return 1 if the element is a processing instruction (C<#PI>) element, +return 0 otherwise. + +=item target + +Return the target of a processing instruction + +=item set_target ($target) + +Set the target of a processing instruction + +=item data + +Return the data part of a processing instruction + +=item set_data ($data) + +Set the data of a processing instruction + +=item set_pi ($target, $data) + +Set the target and data of a processing instruction + +=item pi_string + +Return the string form of a processing instruction +(C<< <?target data?> >>) + +=item is_comment + +Return 1 if the element is a comment (C<#COMMENT>) element, +return 0 otherwise. + +=item set_comment ($comment_text) + +Set the text for a comment + +=item comment + +Return the content of a comment (just the text, not the C<<  >>) + +=item comment_string + +Return the XML string for a comment (C<<  >>) + +Note that an XML comment cannot start or end with a '-', or include '--' +(http://www.w3.org/TR/2008/REC-xml-20081126/#sec-comments), +if that is the case (because you have created the comment yourself presumably, +as it could not be in the input XML), then a space will be inserted before +an initial '-', after a trailing one or between two '-' in the comment +(which could presumably mangle javascript "hidden" in an XHTML comment); + +=item set_ent ($entity) + +Set an (non-expanded) entity (C<#ENT>). C<$entity>) is the entity +text (C<&ent;>) + +=item ent + +Return the entity for an entity (C<#ENT>) element (C<&ent;>) + +=item ent_name + +Return the entity name for an entity (C<#ENT>) element (C<ent>) + +=item ent_string + +Return the entity, either expanded if the expanded version is available, +or non-expanded (C<&ent;>) otherwise + +=item child ($offset, $optional_condition) + +Return the C<$offset>-th child of the element, optionally the C<$offset>-th +child that matches C<$optional_condition>. The children are treated as a list, so +C<< $elt->child( 0) >> is the first child, while C<< $elt->child( -1) >> is +the last child. + +=item child_text ($offset, $optional_condition) + +Return the text of a child or C<undef> if the sibling does not exist. Arguments +are the same as child. + +=item last_child ($optional_condition) + +Return the last child of the element, or the last child matching +C<$optional_condition> (ie the last of the element children matching +the condition). + +=item last_child_text ($optional_condition) + +Same as C<first_child_text> but for the last child. + +=item sibling ($offset, $optional_condition) + +Return the next or previous C<$offset>-th sibling of the element, or the +C<$offset>-th one matching C<$optional_condition>. If C<$offset> is negative then a +previous sibling is returned, if $offset is positive then a next sibling is +returned. C<$offset=0> returns the element if there is no condition or +if the element matches the condition>, C<undef> otherwise. + +=item sibling_text ($offset, $optional_condition) + +Return the text of a sibling or C<undef> if the sibling does not exist. +Arguments are the same as C<sibling>. + +=item prev_siblings ($optional_condition) + +Return the list of previous siblings (optionally matching C<$optional_condition>) +for the element. The elements are ordered in document order. + +=item next_siblings ($optional_condition) + +Return the list of siblings (optionally matching C<$optional_condition>) +following the element. The elements are ordered in document order. + +=item siblings ($optional_condition) + +Return the list of siblings (optionally matching C<$optional_condition>) +of the element (excluding the element itself). The elements are ordered +in document order. + +=item pos ($optional_condition) + +Return the position of the element in the children list. The first child has a +position of 1 (as in XPath). + +If the C<$optional_condition> is given then only siblings that match the condition +are counted. If the element itself does not match the condition then +0 is returned. + +=item atts + +Return a hash ref containing the element attributes + +=item set_atts ({ att1=>$att1_val, att2=> $att2_val... }) + +Set the element attributes with the hash ref supplied as the argument. The previous +attributes are lost (ie the attributes set by C<set_atts> replace all of the +attributes of the element). + +You can also pass a list instead of a hashref: C<< $elt->set_atts( att1 => 'val1',...) >> + +=item del_atts + +Deletes all the element attributes. + +=item att_nb + +Return the number of attributes for the element + +=item has_atts + +Return true if the element has attributes (in fact return the number of +attributes, thus being an alias to C<L<att_nb>> + +=item has_no_atts + +Return true if the element has no attributes, false (0) otherwise + +=item att_names + +return a list of the attribute names for the element + +=item att_xml_string ($att, $options) + +Return the attribute value, where '&', '<' and quote (" or the value of the quote option +at twig creation) are XML-escaped. + +The options are passed as a hashref, setting C<escape_gt> to a true value will also escape +'>' ($elt( 'myatt', { escape_gt => 1 }); + +=item set_id ($id) + +Set the C<id> attribute of the element to the value. +See C<L<elt_id> > to change the id attribute name + +=item id + +Gets the id attribute value + +=item del_id ($id) + +Deletes the C<id> attribute of the element and remove it from the id list +for the document + +=item class + +Return the C<class> attribute for the element (methods on the C<class> +attribute are quite convenient when dealing with XHTML, or plain XML that +will eventually be displayed using CSS) + +=item lclass + +same as class, except that +this method is an lvalue, so you can do C<< $elt->lclass= "foo" >> + +=item set_class ($class) + +Set the C<class> attribute for the element to C<$class> + +=item add_class ($class) + +Add C<$class> to the element C<class> attribute: the new class is added +only if it is not already present. + +Note that classes are then sorted alphabetically, so the C<class> attribute +can be changed even if the class is already there + +=item remove_class ($class) + +Remove C<$class> from the element C<class> attribute. + +Note that classes are then sorted alphabetically, so the C<class> attribute can be +changed even if the class is already there + + +=item add_to_class ($class) + +alias for add_class + +=item att_to_class ($att) + +Set the C<class> attribute to the value of attribute C<$att> + +=item add_att_to_class ($att) + +Add the value of attribute C<$att> to the C<class> attribute of the element + +=item move_att_to_class ($att) + +Add the value of attribute C<$att> to the C<class> attribute of the element +and delete the attribute + +=item tag_to_class + +Set the C<class> attribute of the element to the element tag + +=item add_tag_to_class + +Add the element tag to its C<class> attribute + +=item set_tag_class ($new_tag) + +Add the element tag to its C<class> attribute and sets the tag to C<$new_tag> + +=item in_class ($class) + +Return true (C<1>) if the element is in the class C<$class> (if C<$class> is +one of the tokens in the element C<class> attribute) + +=item tag_to_span + +Change the element tag tp C and set its class to the old tag + +=item tag_to_div + +Change the element tag tp C<div> and set its class to the old tag + +=item DESTROY + +Frees the element from memory. + +=item start_tag + +Return the string for the start tag for the element, including +the C<< /> >> at the end of an empty element tag + +=item end_tag + +Return the string for the end tag of an element. For an empty +element, this returns the empty string (''). + +=item xml_string @optional_options + +Equivalent to C<< $elt->sprint( 1) >>, returns the string for the entire +element, excluding the element's tags (but nested element tags are present) + +The 'C<no_recurse>' option will only return the text of the element, not +of any included sub-elements (same as C<L<xml_text_only>>). + +=item inner_xml + +Another synonym for xml_string + +=item outer_xml + +An other synonym for sprint + +=item xml_text + +Return the text of the element, encoded (and processed by the current +C<L<output_filter>> or C<L<output_encoding>> options, without any tag. + +=item xml_text_only + +Same as C<L<xml_text>> except that the text returned doesn't include +the text of sub-elements. + +=item set_pretty_print ($style) + +Set the pretty print method, amongst 'C<none>' (default), 'C<nsgmls>', +'C<nice>', 'C<indented>', 'C<record>' and 'C<record_c>' + +pretty_print styles: + +=over 4 + +=item none + +the default, no C<\n> is used + +=item nsgmls + +nsgmls style, with C<\n> added within tags + +=item nice + +adds C<\n> wherever possible (NOT SAFE, can lead to invalid XML) + +=item indented + +same as C<nice> plus indents elements (NOT SAFE, can lead to invalid XML) + +=item record + +table-oriented pretty print, one field per line + +=item record_c + +table-oriented pretty print, more compact than C<record>, one record per line + +=back + +=item set_empty_tag_style ($style) + +Set the method to output empty tags, amongst 'C<normal>' (default), 'C<html>', +and 'C<expand>', + +C<normal> outputs an empty tag 'C<< <tag/> >>', C<html> adds a space +'C<< <tag /> >>' for elements that can be empty in XHTML and C<expand> outputs +'C<< <tag></tag> >>' + +=item set_remove_cdata ($flag) + +set (or unset) the flag that forces the twig to output CDATA sections as +regular (escaped) PCDATA + + +=item set_indent ($string) + +Set the indentation for the indented pretty print style (default is 2 spaces) + +=item set_quote ($quote) + +Set the quotes used for attributes. can be 'C<double>' (default) or 'C<single>' + +=item cmp ($elt) + + Compare the order of the 2 elements in a twig. + + C<$a> is the <A>..</A> element, C<$b> is the ... element + + document $a->cmp( $b) + <A> ... </A> ... ... -1 + <A> ... ... ... </A> -1 + ... ... <A> ... </A> 1 + ... <A> ... </A> ... 1 + $a == $b 0 + $a and $b not in the same tree undef + +=item before ($elt) + +Return 1 if C<$elt> starts before the element, 0 otherwise. If the 2 elements +are not in the same twig then return C<undef>. + + if( $a->cmp( $b) == -1) { return 1; } else { return 0; } + +=item after ($elt) + +Return 1 if $elt starts after the element, 0 otherwise. If the 2 elements +are not in the same twig then return C<undef>. + + if( $a->cmp( $b) == -1) { return 1; } else { return 0; } + +=item other comparison methods + +=over 4 + +=item lt + +=item le + +=item gt + +=item ge + +=back + +=item path + +Return the element context in a form similar to XPath's short +form: 'C</root/tag1/../tag>' + +=item xpath + +Return a unique XPath expression that can be used to find the element +again. + +It looks like C</doc/sect[3]/title>: unique elements do not have an index, +the others do. + +=item flush + +flushes the twig up to the current element (strictly equivalent to +C<< $elt->root->flush >>) + +=item private methods + +Low-level methods on the twig: + +=over 4 + +=item set_parent ($parent) + +=item set_first_child ($first_child) + +=item set_last_child ($last_child) + +=item set_prev_sibling ($prev_sibling) + +=item set_next_sibling ($next_sibling) + +=item set_twig_current + +=item del_twig_current + +=item twig_current + +=item contains_text + +=back + +Those methods should not be used, unless of course you find some creative +and interesting, not to mention useful, ways to do it. + +=back + +=head2 cond + +Most of the navigation functions accept a condition as an optional argument +The first element (or all elements for C<L<children> > or +C<L<ancestors> >) that passes the condition is returned. + +The condition is a single step of an XPath expression using the XPath subset +defined by C<L<get_xpath>>. Additional conditions are: + +The condition can be + +=over 4 + +=item #ELT + +return a "real" element (not a PCDATA, CDATA, comment or pi element) + +=item #TEXT + +return a PCDATA or CDATA element + +=item regular expression + +return an element whose tag matches the regexp. The regexp has to be created +with C<qr//> (hence this is available only on perl 5.005 and above) + +=item code reference + +applies the code, passing the current element as argument, if the code returns +true then the element is returned, if it returns false then the code is applied +to the next candidate. + +=back + +=head2 XML::Twig::XPath + +XML::Twig implements a subset of XPath through the C<L<get_xpath>> method. + +If you want to use the whole XPath power, then you can use C<XML::Twig::XPath> +instead. In this case C<XML::Twig> uses C<XML::XPath> to execute XPath queries. +You will of course need C<XML::XPath> installed to be able to use C<XML::Twig::XPath>. + +See L<XML::XPath> for more information. + +The methods you can use are: + +=over 4 + +=item findnodes ($path) + +return a list of nodes found by C<$path>. + +=item findnodes_as_string ($path) + +return the nodes found reproduced as XML. The result is not guaranteed +to be valid XML though. + +=item findvalue ($path) + +return the concatenation of the text content of the result nodes + +=back + +In order for C<XML::XPath> to be used as the XPath engine the following methods +are included in C<XML::Twig>: + +in XML::Twig + +=over 4 + +=item getRootNode + +=item getParentNode + +=item getChildNodes + +=back + +in XML::Twig::Elt + +=over 4 + +=item string_value + +=item toString + +=item getName + +=item getRootNode + +=item getNextSibling + +=item getPreviousSibling + +=item isElementNode + +=item isTextNode + +=item isPI + +=item isPINode + +=item isProcessingInstructionNode + +=item isComment + +=item isCommentNode + +=item getTarget + +=item getChildNodes + +=item getElementById + +=back + +=head2 XML::Twig::XPath::Elt + +The methods you can use are the same as on C<XML::Twig::XPath> elements: + +=over 4 + +=item findnodes ($path) + +return a list of nodes found by C<$path>. + +=item findnodes_as_string ($path) + +return the nodes found reproduced as XML. The result is not guaranteed +to be valid XML though. + +=item findvalue ($path) + +return the concatenation of the text content of the result nodes + +=back + + +=head2 XML::Twig::Entity_list + +=over 4 + +=item new + +Create an entity list. + +=item add ($ent) + +Add an entity to an entity list. + +=item add_new_ent ($name, $val, $sysid, $pubid, $ndata, $param) + +Create a new entity and add it to the entity list + +=item delete ($ent or $tag). + +Delete an entity (defined by its name or by the Entity object) +from the list. + +=item print ($optional_filehandle) + +Print the entity list. + +=item list + +Return the list as an array + +=back + + +=head2 XML::Twig::Entity + +=over 4 + +=item new ($name, $val, $sysid, $pubid, $ndata, $param) + +Same arguments as the Entity handler for XML::Parser. + +=item print ($optional_filehandle) + +Print an entity declaration. + +=item name + +Return the name of the entity + +=item val + +Return the value of the entity + +=item sysid + +Return the system id for the entity (for NDATA entities) + +=item pubid + +Return the public id for the entity (for NDATA entities) + +=item ndata + +Return true if the entity is an NDATA entity + +=item param + +Return true if the entity is a parameter entity + + +=item text + +Return the entity declaration text. + +=back + + +=head1 EXAMPLES + +Additional examples (and a complete tutorial) can be found on the +F<XML::Twig PageL<http://www.xmltwig.org/xmltwig/>> + +To figure out what flush does call the following script with an +XML file and an element name as arguments + + use XML::Twig; + + my ($file, $elt)= @ARGV; + my $t= XML::Twig->new( twig_handlers => + { $elt => sub {$_[0]->flush; print "\n[flushed here]\n";} }); + $t->parsefile( $file, ErrorContext => 2); + $t->flush; + print "\n"; + + +=head1 NOTES + +=head2 Subclassing XML::Twig + +Useful methods: + +=over 4 + +=item elt_class + +In order to subclass C<XML::Twig> you will probably need to subclass also +C<L<XML::Twig::Elt>>. Use the C<elt_class> option when you create the +C<XML::Twig> object to get the elements created in a different class +(which should be a subclass of C<XML::Twig::Elt>. + +=item add_options + +If you inherit C<XML::Twig> new method but want to add more options to it +you can use this method to prevent XML::Twig to issue warnings for those +additional options. + +=back + +=head2 DTD Handling + +There are 3 possibilities here. They are: + +=over 4 + +=item No DTD + +No doctype, no DTD information, no entity information, the world is simple... + +=item Internal DTD + +The XML document includes an internal DTD, and maybe entity declarations. + +If you use the load_DTD option when creating the twig the DTD information and +the entity declarations can be accessed. + +The DTD and the entity declarations will be C<flush>'ed (or C<print>'ed) either +as is (if they have not been modified) or as reconstructed (poorly, comments +are lost, order is not kept, due to it's content this DTD should not be viewed +by anyone) if they have been modified. You can also modify them directly by +changing the C<< $twig->{twig_doctype}->{internal} >> field (straight from +XML::Parser, see the C<Doctype> handler doc) + +=item External DTD + +The XML document includes a reference to an external DTD, and maybe entity +declarations. + +If you use the C<load_DTD> when creating the twig the DTD information and the +entity declarations can be accessed. The entity declarations will be +C<flush>'ed (or C<print>'ed) either as is (if they have not been modified) or +as reconstructed (badly, comments are lost, order is not kept). + +You can change the doctype through the C<< $twig->set_doctype >> method and +print the dtd through the C<< $twig->dtd_text >> or C<< $twig->dtd_print >> + methods. + +If you need to modify the entity list this is probably the easiest way to do it. + +=back + + +=head2 Flush + +Remember that element handlers are called when the element is CLOSED, so +if you have handlers for nested elements the inner handlers will be called +first. It makes it for example trickier than it would seem to number nested +sections (or clauses, or divs), as the titles in the inner sections are handled +before the outer sections. + + +=head1 BUGS + +=over 4 + +=item segfault during parsing + +This happens when parsing huge documents, or lots of small ones, with a version +of Perl before 5.16. + +This is due to a bug in the way weak references are handled in Perl itself. + +The fix is either to upgrade to Perl 5.16 or later (C<perlbrew> is a great +tool to manage several installations of perl on the same machine). + +An other, NOT RECOMMENDED, way of fixing the problem, is to switch off weak +references by writing C<XML::Twig::_set_weakrefs( 0);> at the top of the code. +This is totally unsupported, and may lead to other problems though, + +=item entity handling + +Due to XML::Parser behaviour, non-base entities in attribute values disappear if +they are not declared in the document: +C<att="val&ent;"> will be turned into C<< att => val >>, unless you use the +C<keep_encoding> argument to C<< XML::Twig->new >> + +=item DTD handling + +The DTD handling methods are quite bugged. No one uses them and +it seems very difficult to get them to work in all cases, including with +several slightly incompatible versions of XML::Parser and of libexpat. + +Basically you can read the DTD, output it back properly, and update entities, +but not much more. + +So use XML::Twig with standalone documents, or with documents referring to an +external DTD, but don't expect it to properly parse and even output back the +DTD. + +=item memory leak + +If you use a REALLY old Perl (5.005!) and +a lot of twigs you might find that you leak quite a lot of memory +(about 2Ks per twig). You can use the C<L<dispose> > method to free +that memory after you are done. + +If you create elements the same thing might happen, use the C<L<delete>> +method to get rid of them. + +Alternatively installing the C<Scalar::Util> (or C<WeakRef>) module on a version +of Perl that supports it (>5.6.0) will get rid of the memory leaks automagically. + +=item ID list + +The ID list is NOT updated when elements are cut or deleted. + +=item change_gi + +This method will not function properly if you do: + + $twig->change_gi( $old1, $new); + $twig->change_gi( $old2, $new); + $twig->change_gi( $new, $even_newer); + +=item sanity check on XML::Parser method calls + +XML::Twig should really prevent calls to some XML::Parser methods, especially +the C<setHandlers> method. + +=item pretty printing + +Pretty printing (at least using the 'C<indented>' style) is hard to get right! +Only elements that belong to the document will be properly indented. Printing +elements that do not belong to the twig makes it impossible for XML::Twig to +figure out their depth, and thus their indentation level. + +Also there is an unavoidable bug when using C<flush> and pretty printing for +elements with mixed content that start with an embedded element: + + <elt>btotobold</elt> + + will be output as + + <elt> + btotobold</elt> + +if you flush the twig when you find the C<< >> element + + +=back + +=head1 Globals + +These are the things that can mess up calling code, especially if threaded. +They might also cause problem under mod_perl. + +=over 4 + +=item Exported constants + +Whether you want them or not you get them! These are subroutines to use +as constant when creating or testing elements + + PCDATA return '#PCDATA' + CDATA return '#CDATA' + PI return '#PI', I had the choice between PROC and PI :--( + +=item Module scoped values: constants + +these should cause no trouble: + + %base_ent= ( '>' => '>', + '<' => '<', + '&' => '&', + "'" => ''', + '"' => '"', + ); + CDATA_START = "<![CDATA["; + CDATA_END = "]]>"; + PI_START = "<?"; + PI_END = "?>"; + COMMENT_START = ""; + +pretty print styles + + ( $NSGMLS, $NICE, $INDENTED, $INDENTED_C, $WRAPPED, $RECORD1, $RECORD2)= (1..7); + +empty tag output style + + ( $HTML, $EXPAND)= (1..2); + +=item Module scoped values: might be changed + +Most of these deal with pretty printing, so the worst that can +happen is probably that XML output does not look right, but is +still valid and processed identically by XML processors. + +C<$empty_tag_style> can mess up HTML bowsers though and changing C<$ID> +would most likely create problems. + + $pretty=0; # pretty print style + $quote='"'; # quote for attributes + $INDENT= ' '; # indent for indented pretty print + $empty_tag_style= 0; # how to display empty tags + $ID # attribute used as an id ('id' by default) + +=item Module scoped values: definitely changed + +These 2 variables are used to replace tags by an index, thus +saving some space when creating a twig. If they really cause +you too much trouble, let me know, it is probably possible to +create either a switch or at least a version of XML::Twig that +does not perform this optimization. + + %gi2index; # tag => index + @index2gi; # list of tags + +=back + +If you need to manipulate all those values, you can use the following methods on the +XML::Twig object: + +=over 4 + +=item global_state + +Return a hashref with all the global variables used by XML::Twig + +The hash has the following fields: C<pretty>, C<quote>, C<indent>, +C<empty_tag_style>, C<keep_encoding>, C<expand_external_entities>, +C<output_filter>, C<output_text_filter>, C<keep_atts_order> + +=item set_global_state ($state) + +Set the global state, C<$state> is a hashref + +=item save_global_state + +Save the current global state + +=item restore_global_state + +Restore the previously saved (using C<Lsave_global_state>> state + +=back + +=head1 TODO + +=over 4 + +=item SAX handlers + +Allowing XML::Twig to work on top of any SAX parser + +=item multiple twigs are not well supported + +A number of twig features are just global at the moment. These include +the ID list and the "tag pool" (if you use C<change_gi> then you change the tag +for ALL twigs). + +A future version will try to support this while trying not to be to +hard on performance (at least when a single twig is used!). + +=back + +=head1 AUTHOR + +Michel Rodriguez <mirod@cpan.org> + +=head1 LICENSE + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +Bug reports should be sent using: +F<RT L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-Twig>> + +Comments can be sent to mirod@cpan.org + +The XML::Twig page is at L<http://www.xmltwig.org/xmltwig/> +It includes the development version of the module, a slightly better version +of the documentation, examples, a tutorial and a: +F<Processing XML efficiently with Perl and XML::Twig: +L<http://www.xmltwig.org/xmltwig/tutorial/index.html>> + +=head1 SEE ALSO + +Complete docs, including a tutorial, examples, an easier to use HTML version of +the docs, a quick reference card and a FAQ are available at +L<http://www.xmltwig.org/xmltwig/> + +git repository at L<http://github.com/mirod/xmltwig> + +L<XML::Parser>, L<XML::Parser::Expat>, L<XML::XPath>, L<Encode>, +L<Text::Iconv>, L<Scalar::Utils> + + +=head2 Alternative Modules + +XML::Twig is not the only XML::Processing module available on CPAN (far from +it!). + +The main alternative I would recommend is L<XML::LibXML>. + +Here is a quick comparison of the 2 modules: + +XML::LibXML, actually C<libxml2> on which it is based, sticks to the standards, +and implements a good number of them in a rather strict way: XML, XPath, DOM, +RelaxNG, I must be forgetting a couple (XInclude?). It is fast and rather +frugal memory-wise. + +XML::Twig is older: when I started writing it XML::Parser/expat was the only +game in town. It implements XML and that's about it (plus a subset of XPath, +and you can use XML::Twig::XPath if you have XML::XPathEngine installed for full +support). It is slower and requires more memory for a full tree than +XML::LibXML. On the plus side (yes, there is a plus side!) it lets you process +a big document in chunks, and thus let you tackle documents that couldn't be +loaded in memory by XML::LibXML, and it offers a lot (and I mean a LOT!) of +higher-level methods, for everything, from adding structure to "low-level" XML, +to shortcuts for XHTML conversions and more. It also DWIMs quite a bit, getting +comments and non-significant whitespaces out of the way but preserving them in +the output for example. As it does not stick to the DOM, is also usually leads +to shorter code than in XML::LibXML. + +Beyond the pure features of the 2 modules, XML::LibXML seems to be preferred by +"XML-purists", while XML::Twig seems to be more used by Perl Hackers who have +to deal with XML. As you have noted, XML::Twig also comes with quite a lot of +docs, but I am sure if you ask for help about XML::LibXML here or on Perlmonks +you will get answers. + +Note that it is actually quite hard for me to compare the 2 modules: on one hand +I know XML::Twig inside-out and I can get it to do pretty much anything I need +to (or I improve it ;--), while I have a very basic knowledge of XML::LibXML. +So feature-wise, I'd rather use XML::Twig ;--). On the other hand, I am +painfully aware of some of the deficiencies, potential bugs and plain ugly code +that lurk in XML::Twig, even though you are unlikely to be affected by them +(unless for example you need to change the DTD of a document programmatically), +while I haven't looked much into XML::LibXML so it still looks shinny and clean +to me. + +That said, if you need to process a document that is too big to fit memory +and XML::Twig is too slow for you, my reluctant advice would be to use "bare" +XML::Parser. It won't be as easy to use as XML::Twig: basically with XML::Twig +you trade some speed (depending on what you do from a factor 3 to... none) +for ease-of-use, but it will be easier IMHO than using SAX (albeit not +standard), and at this point a LOT faster (see the last test in +L<http://www.xmltwig.org/article/simple_benchmark/>). + +=cut + + Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile_1900.xls and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile_1900.xls differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile_1900.xlsx and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile_1900.xlsx differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile_1904.xls and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile_1904.xls differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile_1904.xlsx and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile_1904.xlsx differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile.xls and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile.xls differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/ExampleExcelFile.xlsx and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/ExampleExcelFile.xlsx differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/wide.xls and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/wide.xls differ Binary files /tmp/WlnUgzz6bE/gdata-2.13.3/inst/xls/wide.xlsx and /tmp/J1mSmQsMZw/gdata-2.17.0/inst/xls/wide.xlsx differ diff -Nru gdata-2.13.3/man/first.Rd gdata-2.17.0/man/first.Rd --- gdata-2.13.3/man/first.Rd 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/man/first.Rd 2015-04-28 06:11:59.000000000 +0000 @@ -0,0 +1,55 @@ +\name{first} +\alias{first} +\alias{last} +\title{Return first or last element of an object} +\description{ + Return first or last element of an object. These functions are convenience + wrappers for \code{head(x, n=1, ...)} and \code{tail(x, n=1, ...)}. + } +\usage{ +first(x, n=1, ...) +last(x, n=1, ...) +} +\arguments{ + \item{x}{data object} + \item{n}{a single integer. If positive, size for the resulting object: + number of elements for a vector (including lists), rows for a + matrix or data frame or lines for a function. If negative, + all but the 'n' last/first number of elements of 'x'.} + \item{...}{arguments to be passed to or from other methods.} +} +\value{ + An object (usually) like 'x' but generally smaller. +} +\author{ + Gregory R. Warnes \email{greg@warnes.net} +} +\seealso{ + \code{\link[utils]{head}}, + \code{\link[utils]{tail}}, + \code{\link{left}}, + \code{\link{right}} +} +\examples{ +## works for vectors.. +v <- 1:10 +first(v) +last(v) + +## and for lists +l <- list(a=1, b=2, c=3) +first(l) +last(l) + +## and data.frames +df <- data.frame(a=1:2, b=3:4, c=5:6) +first(df) +last(df) + +## and matrixes +m <- as.matrix(df) +first(m) +last(m) + +} +\keyword{ manip } diff -Nru gdata-2.13.3/man/humanReadable.Rd gdata-2.17.0/man/humanReadable.Rd --- gdata-2.13.3/man/humanReadable.Rd 2014-01-03 19:32:44.000000000 +0000 +++ gdata-2.17.0/man/humanReadable.Rd 2015-04-25 06:34:06.000000000 +0000 @@ -1,44 +1,43 @@ -% humanReadable.Rd -%-------------------------------------------------------------------------- -% What: Print byte size in human readable format man page -% $Id$ -% Time-stamp: <2008-12-30 13:26:35 ggorjan> -%-------------------------------------------------------------------------- - \name{humanReadable} \alias{humanReadable} -\title{Print byte size in human readable format} +\title{Print Byte Size in Human Readable Format} \description{ -\code{humanReadable} converts byte size in human readable format such as +\code{humanReadable} converts integer byte sizes to a human readable units such as kB, MB, GB, etc. } \usage{ - -humanReadable(x, standard="SI", digits=1, width=3, sep=" ") - +humanReadable(x, units="auto", standard=c("IEC", "SI", "Unix"), + digits=1, width=NULL, sep=" ", justify=c("right", "left") ) } \arguments{ \item{x}{integer, byte size} - \item{standard}{character, "SI" for powers of 1000 or anything else for - powers of 1024, see details} + \item{standard}{character, "IEC" for powers of 1024 ('MiB'), "SI" for + powers of 1000 ('MB'), or "Unix" for powers of 1024 ('M'). See + details.} + \item{units}{character, unit to use for all values (optional), one of + "auto", "bytes", or an appropriate unit corresponding to + \code{standard}.} \item{digits}{integer, number of digits after decimal point} \item{width}{integer, width of number string} \item{sep}{character, separator between number and unit} + \item{justify}{two-element vector specifiy the alignment for the number + and unit components of the size. Each element should be one of + "none", "left", "right", or "center"} } \details{ -Basic unit used to store information in computers is a bit. Bits are +The basic unit used to store information in computers is a bit. Bits are represented as zeroes and ones - binary number system. Although, the binary number system is not the same as the decimal number system, decimal prefixes -for binary multiples such as kilo and mega are often used. In the decimal system +for binary multiples such as kilo and mega are often used. In the decimal system kilo represent 1000, which is close to \eqn{1024 = 2^{10}} in the binary system. This sometimes causes problems as it is not clear which powers (2 or 10) are used in a notation like 1 kB. To overcome this problem International Electrotechnical @@ -66,14 +65,30 @@ } where Zi and Yi are GNU extensions to IEC. To get the output in the decimal -system (powers of 1000) use \code{standard="SI"}. Otherwise IEC standard -(powers of 1024) is used. +system (powers of 1000) use \code{standard="SI"}. To obtain IEC standard +(powers of 1024) use \code{standard="IEC"}. + +In addition, single-character units are provided that follow (and +extend) the Unix pattern (use \code{standard="Unix"}): + +\tabular{lrcll}{ +Name \tab System \tab Symbol \tab Size \tab Conversion \cr +byte \tab binary \tab B \tab \eqn{2^3} \tab 8 bits \cr +kibibyte \tab binary \tab K \tab \eqn{2^{10}} \tab 1024 bytes \cr +mebibyte \tab binary \tab M \tab \eqn{(2^{10})^2} \tab 1024 kibibytes\cr +gibibyte \tab binary \tab G \tab \eqn{(2^{10})^3} \tab 1024 mebibytes\cr +tebibyte \tab binary \tab T \tab \eqn{(2^{10})^4} \tab 1024 gibibytes\cr +pebibyte \tab binary \tab P \tab \eqn{(2^{10})^5} \tab 1024 tebibytes\cr +exbibyte \tab binary \tab E \tab \eqn{(2^{10})^6} \tab 1024 pebibytes\cr +zebibyte \tab binary \tab Z \tab \eqn{(2^{10})^7} \tab 1024 exbibytes\cr +yottabyte \tab binary \tab Y \tab \eqn{(2^{10})^8} \tab 1024 zebibytes\cr +} For printout both \code{digits} and \code{width} can be specified. If \code{width} is \code{NULL}, all values have given number of digits. If \code{width} is not \code{NULL}, output is rounded to a given width and -formated similar to human readable format of \code{ls}, \code{df} or -\code{du} shell commands. +formated similar to human readable format of the Unix \code{ls}, +\code{df} or \code{du} shell commands. } @@ -96,33 +111,40 @@ } -\author{Ales Korosec and Gregor Gorjanc} +\author{Ales Korosec, Gregor Gorjanc, and Gregory R. Warnes + \email{greg@warnes.net}} + \seealso{ - \code{\link{object.size}}, \code{\link[gdata]{ll}} + \code{\link{object.size}} in package 'gdata', + \code{\link[utils]{object.size}} in package 'utils', + \code{\link[gdata]{ll}} } \examples{ -baseSI <- 10 -powerSI <- seq(from=3, to=27, by=3) -SI0 <- (baseSI)^powerSI -k <- length(SI0) - 1 -SI1 <- SI0 - SI0 / c(2, runif(n=k, min=1.01, max=5.99)) -SI2 <- SI0 + SI0 / c(2, runif(n=k, min=1.01, max=5.99)) - -baseIEC <- 2 -powerIEC <- seq(from=10, to=90, by=10) -IEC0 <- (baseIEC)^powerIEC -IEC1 <- IEC0 - IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) -IEC2 <- IEC0 + IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) - -cbind(humanReadable(x=SI1, width=NULL, digits=3), - humanReadable(x=SI0, width=NULL, digits=2), - humanReadable(x=SI2, width=NULL, digits=1), - humanReadable(x=IEC1, standard="IEC", width=7, digits=3), - humanReadable(x=IEC0, standard="IEC", width=7, digits=2), - humanReadable(x=IEC2, standard="IEC", width=7, digits=1)) +# Simple example: maximum addressible size of 32 bit pointer +humanReadable(2^32-1) +humanReadable(2^32-1, standard="IEC") +humanReadable(2^32-1, standard="SI") +humanReadable(2^32-1, standard="Unix") + +humanReadable(2^32-1, unit="MiB") +humanReadable(2^32-1, standard="IEC", unit="MiB") +humanReadable(2^32-1, standard="SI", unit="MB") +humanReadable(2^32-1, standard="Unix", unit="M") + +# Vector of sizes +matrix(humanReadable(c(60810, 124141, 124, 13412513), width=4)) +matrix(humanReadable(c(60810, 124141, 124, 13412513), width=4, unit="KiB")) + +# Specify digits rather than width +matrix(humanReadable(c(60810, 124141, 124, 13412513), width=NULL, digits=2)) + +# Change the justification +matrix(humanReadable(c(60810, 124141, 124, 13412513), width=NULL, + justify=c("right", "right") )) + } \keyword{misc} diff -Nru gdata-2.13.3/man/left.Rd gdata-2.17.0/man/left.Rd --- gdata-2.13.3/man/left.Rd 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/man/left.Rd 2015-04-13 23:37:08.000000000 +0000 @@ -0,0 +1,39 @@ +\name{left} +\alias{right} +\alias{left} +\title{Return the leftmost or rightmost columns of a matrix or dataframe} +\description{ + Return the leftmost or rightmost or columns of a matrix or dataframe +} +\usage{ +right(x, n = 6) +left(x, n=6) +} +\arguments{ + \item{x}{Matrix or dataframe} + \item{n}{Number of columns to return} +} +\value{ + An object consisting of the leftmost or rightmost \code{n} columns + of \code{x}. +} +\author{ + Gregory R. Warnes \email{greg@warnes.net} +} +\seealso{ + \code{\link{first}}, + \code{\link{last}}, + \code{\link[utils]{head}}, + \code{\link[utils]{tail}} +} +\examples{ + m <- matrix( 1:100, ncol=10 ) + colnames(m) <- paste("Col",1:10, sep="_") + left(m) + right(m) + + d <- as.data.frame(m) + left(d) + right(d) +} +\keyword{ manip } diff -Nru gdata-2.13.3/man/object.size.Rd gdata-2.17.0/man/object.size.Rd --- gdata-2.13.3/man/object.size.Rd 2014-01-03 19:32:43.000000000 +0000 +++ gdata-2.17.0/man/object.size.Rd 2015-04-25 06:52:28.000000000 +0000 @@ -1,70 +1,99 @@ -% File src/library/utils/man/object.size.Rd +% Come material taken from src/library/utils/man/object.size.Rd % Part of the R package, http://www.R-project.org % Copyright 1995-2007 R Core Development Team % Distributed under GPL 2 or later \name{object.size} \alias{object.size} -\alias{print.object_size} -\alias{c.object_size} -\alias{as.object_size} -\alias{is.object_size} +\alias{c.object_sizes} +\alias{as.object_sizes} +\alias{is.object_sizes} +\alias{format.object_sizes} +\alias{print.object_sizes} -\title{Report the Space Allocated for an Object} +\title{Report the Space Allocated for Objects} \description{ - Provides an estimate of the memory that is being used to store an \R object. + Provides an estimate of the memory that is being used to store \R objects. } \usage{ object.size(\dots) -\method{print}{object_size}(x, quote=FALSE, humanReadable, \dots) +\method{is}{object_sizes}(x) + +\method{as}{object_sizes}(x) + +\method{c}{object_sizes}(\dots, recursive=FALSE) + +\method{format}{object_sizes}(x, humanReadable=getOption("humanReadable"), standard="IEC", units, + digits=1, width=NULL, sep=" ", justify = c("right", "left"), +\dots) + +\method{print}{object_sizes}(x, quote=FALSE, humanReadable=getOption("humanReadable"), + standard="IEC", units, digits=1, width=NULL, sep=" ", + justify = c("right", "left"), \dots) + } \arguments{ - \item{\dots}{\code{object.size}: \R objects; \code{print}; arguments - to be passed to or from other methods.} + \item{\dots}{\code{object.size}: \R objects; + \code{print} and \code{format}: arguments to be passed to other + methods. + } \item{x}{output from \code{object.size}} \item{quote}{logical, indicating whether or not the result should be printed with surrounding quotes.} \item{humanReadable}{logical, use the \dQuote{human readable} format.} + \item{standard,units,digits,width,sep,justify}{See the man page for + \code{\link{humanReadable}}. + } + \item{recursive}{See the man page for \code{\link[base]{c}}. } } \details{ - This is a modified copy from the utils package in R as fo 2008-12-15. + \emph{This is a modified copy of the man page for utils::object.size in R + 2.2.1.} + + Exactly which parts of the memory allocation should be attributed + to which object is not clear-cut. This function merely provides a + rough indication: it should be reasonably accurate for atomic + vectors, but does not detect if elements of a list are shared, for + example. (Sharing amongst elements of a character vector is taken + into account, but not that between character vectors in a single + object.) - Exactly which parts of the memory allocation should be attributed to - which object is not clear-cut. This function merely provides a rough - indication: it should be reasonably accurate for atomic vectors, but - does not detect if elements of a list are shared, for example. - (Sharing amongst elements of a character vector is taken into account, - but not that between character vectors in a single object.) - - The calculation is of the size of the object, and excludes the space - needed to store its name in the symbol table. + The calculation is of the size of the object, and excludes the + space needed to store its name in the symbol table. - Associated space (e.g. the environment of a function and what the + Associated space (e.g., the environment of a function and what the pointer in a \code{EXTPTRSXP} points to) is not included in the calculation. - Object sizes are larger on 64-bit platforms than 32-bit ones, but will - very likely be the same on different platforms with the same word - length and pointer size. + Object sizes are larger on 64-bit builds than 32-bit ones, but + will very likely be the same on different platforms with the same + word length and pointer size. % Modificitaion start - Class of returned object is \code{c("byte", "numeric")} with + \emph{Changes} + + Class of returned object is \code{c("object_sizes", "numeric")} with appropriate \code{print} and \code{c} methods. By default \code{object.size} outputs size in bytes, but human readable format similar to \code{ls}, \code{df} or \code{du} shell - commands can be invoked with \code{options(humanReadable=TRUE)}. + commands can be displayed by calling \code{humanReadable} directly, + calling \code{print} with the argument \code{humanReadable=TRUE}, or + by setting \code{options(humanReadable=TRUE)}. + % Modificitaion end } \value{ - An object of class \code{"object.size"} with a length-one double value, - an estimate of the memory allocation attributable to the object in bytes. + A numeric vector class \code{c("object_sizes", "numeric")} containing + estimated memory allocation attributable to the objects in bytes. } \seealso{ - \code{\link{Memory-limits}} for the design limitations on object size. + \code{\link[utils]{object.size}} in package 'utils' for the standard + version of this function, + \code{\link{Memory-limits}} for the design limitations on object size, \code{\link{humanReadable}} for human readable format. } @@ -72,14 +101,35 @@ object.size(letters) object.size(ls) ## find the 10 largest objects in the base package -z <- sapply(ls("package:base"), function(x) - object.size(get(x, envir = baseenv()))) -(tmp <- as.matrix(rev(sort(z))[1:10])) +allObj <- sapply(ls("package:base"), + function(x) + object.size(get(x, envir = baseenv())) + ) + +( bigObj <- as.object_sizes(rev(sort(allObj))[1:10] ) ) +print(bigObj, humanReadable=TRUE) + + +as.object_sizes(14567567) + +\dontshow{ + optionsOrig <- options("humanReadable") +} -as.object_size(14567567) options(humanReadable=TRUE) -(z <- object.size(letters, c(letters, letters), rep(letters, 100), rep(letters, 10000))) -is.object_size(z) -as.object_size(14567567) +( + z <- object.size(letters, + c(letters, letters), + rep(letters, 100), + rep(letters, 10000) + ) +) +is.object_sizes(z) +as.object_sizes(14567567) + +\dontshow{ + options(optionsOrig) +} + } \keyword{utilities} diff -Nru gdata-2.13.3/man/reorder.Rd gdata-2.17.0/man/reorder.Rd --- gdata-2.13.3/man/reorder.Rd 2014-01-03 19:32:44.000000000 +0000 +++ gdata-2.17.0/man/reorder.Rd 2015-04-28 05:40:21.000000000 +0000 @@ -1,5 +1,3 @@ -% $Id: reorder.Rd 1435 2010-05-02 06:11:26Z warnes $ - \name{reorder.factor} \alias{reorder.factor} \title{Reorder the Levels of a Factor} @@ -7,13 +5,7 @@ Reorder the levels of a factor } \usage{ -\method{reorder}{factor}(x, - X, - FUN, - ..., - order=is.ordered(x), - new.order, - sort=mixedsort) +\method{reorder}{factor}(x, X, FUN, ..., order=is.ordered(x), new.order, sort=mixedsort) } \arguments{ \item{x}{factor} @@ -38,50 +30,59 @@ The groups are then sorted by this value, and the resulting order is used for the new factor level names. - If \code{new.order} is provided: For a numeric vector, the new factor - level names are constructed by reordering the factor levels according - to the numeric values. For vectors, \code{new.order} gives the list of - new factor level names. In either case levels omitted from - \code{new.order} will become missing (\code{NA}) values. - - If \code{sort} is provided (as it is by default): The new - factor level names are generated by applying the supplied function - to the existing factor level names. With \code{sort=mixedsort} the - factor levels are sorted so that combined numeric and character - strings are sorted in according to character rules on the character - sections (including ignoring case), and the numeric rules for the - numeric sections. See \code{\link[gtools]{mixedsort}} for details. -} -\value{ - A new factor with reordered levels + If \code{new.order} is a numeric vector, the new factor level names + are constructed by reordering the factor levels according to the + numeric values. If \code{new.order} is a chraccter vector, + \code{new.order} gives the list of new factor level names. In either + case levels omitted from \code{new.order} will become missing + (\code{NA}) values. + + If \code{sort} is provided (as it is by default): The new factor level + names are generated by calling the function specified by \code{sort} + to the existing factor level \emph{names}. With \code{sort=mixedsort} + (the default) the factor levels are sorted so that combined numeric + and character strings are sorted in according to character rules on + the character sections (including ignoring case), and the numeric + rules for the numeric sections. See \code{\link[gtools]{mixedsort}} + for details. } +\value{ A new factor with reordered levels } \author{Gregory R. Warnes \email{greg@warnes.net}} -\seealso{\code{\link{factor}} and \code{\link[stats]{reorder}}} +\seealso{ + \code{\link{factor}} + and + \code{\link[stats]{reorder}} +} \examples{ + +\dontshow{ + set.seed(123456) +} + # Create a 4 level example factor trt <- factor( sample( c("PLACEBO", "300 MG", "600 MG", "1200 MG"), 100, replace=TRUE ) ) summary(trt) # Note that the levels are not in a meaningful order. - # Change the order to something useful - # default "mixedsort" ordering + # Change the order to something useful.. + # - default "mixedsort" ordering trt2 <- reorder(trt) summary(trt2) - # using indexes: + # - using indexes: trt3 <- reorder(trt, new.order=c(4, 2, 3, 1)) summary(trt3) - # using label names: + # - using label names: trt4 <- reorder(trt, new.order=c("PLACEBO", "300 MG", "600 MG", "1200 MG")) summary(trt4) - # using frequency - trt5 <- reorder(trt, X=as.numeric(trt), FUN=length) + # - using frequency + trt5 <- reorder(trt, X=rnorm(100), FUN=mean) summary(trt5) - # drop out the '300 MG' level + # Drop out the '300 MG' level trt6 <- reorder(trt, new.order=c("PLACEBO", "600 MG", "1200 MG")) summary(trt6) } diff -Nru gdata-2.13.3/man/upperTriangle.Rd gdata-2.17.0/man/upperTriangle.Rd --- gdata-2.13.3/man/upperTriangle.Rd 2014-01-03 19:32:43.000000000 +0000 +++ gdata-2.17.0/man/upperTriangle.Rd 2015-06-29 22:33:46.000000000 +0000 @@ -8,15 +8,18 @@ Extract or replace the upper/lower triangular portion of a matrix } \usage{ -upperTriangle(x, diag=FALSE) -upperTriangle(x, diag=FALSE) <- value -lowerTriangle(x, diag=FALSE) -lowerTriangle(x, diag=FALSE) <- value +upperTriangle(x, diag=FALSE, byrow=FALSE) +upperTriangle(x, diag=FALSE, byrow=FALSE) <- value +lowerTriangle(x, diag=FALSE, byrow=FALSE) +lowerTriangle(x, diag=FALSE, byrow=FALSE) <- value } %- maybe also 'usage' for other objects documented here. \arguments{ \item{x}{Matrix} \item{diag}{Logical. If \code{TRUE}, include the matrix diagonal.} + \item{byrow}{Logical. If \code{FALSE}, return/replace elements in + column-wise order. If \code{TRUE}, return/replace elements in + row-wise order.} \item{value}{Either a single value or a vector of length equal to that of the current upper/lower triangular. Should be of a mode which can be coerced to that of \code{x}.} @@ -25,19 +28,35 @@ \value{ \code{upperTriangle(x)} and \code{lowerTriangle(x)} return the upper or lower triangle of matrix x, respectively. The assignment forms - replace the upper or lower traingular area of the - matrix with the provided value(s). + replace the upper or lower triangular area of the + matrix with the provided value(s). } +\note{ + By default, the elements are returned/replaced in R's default column-wise order. Thus + \preformatted{ lowerTriangle(x) <- upperTriangle(x)} + will not yield a symmetric matrix. Instead use: + \preformatted{ lowerTriangle(x) <- upperTriangle(x, byrow=TRUE)} + or equivalently: + \preformatted{ lowerTriangle(x, byrow=TRUE) <- upperTriangle(x)} +} + \author{Gregory R. Warnes \email{greg@warnes.net}} -\seealso{ \code{\link[base]{diag}} } +\seealso{ + \code{\link[base]{diag}}, + \code{\link[base]{lower.tri}}, + \code{\link[base]{upper.tri}} +} \examples{ x <- matrix( 1:25, nrow=5, ncol=5) x upperTriangle(x) upperTriangle(x, diag=TRUE) + upperTriangle(x, diag=TRUE, byrow=TRUE) + lowerTriangle(x) lowerTriangle(x, diag=TRUE) + lowerTriangle(x, diag=TRUE, byrow=TRUE) upperTriangle(x) <- NA x @@ -51,5 +70,11 @@ lowerTriangle(x, diag=TRUE) <- 1:15 x + ## Copy lower triangle into upper triangle to make + ## the matrix (diagonally) symmetric + x <- matrix(LETTERS[1:25], nrow=5, ncol=5, byrow=TRUE) + x + lowerTriangle(x) = upperTriangle(x, byrow=TRUE) + x } \keyword{array} diff -Nru gdata-2.13.3/man/write.fwf.Rd gdata-2.17.0/man/write.fwf.Rd --- gdata-2.13.3/man/write.fwf.Rd 2014-01-03 19:32:43.000000000 +0000 +++ gdata-2.17.0/man/write.fwf.Rd 2015-04-23 02:37:51.000000000 +0000 @@ -1,7 +1,7 @@ % write.fwf.Rd %-------------------------------------------------------------------------- % What: Write fixed width format man page -% $Id: write.fwf.Rd 1459 2010-11-12 19:08:12Z warnes $ +% $Id: write.fwf.Rd 1928 2015-04-14 22:02:01Z warnes $ % Time-stamp: <2008-08-05 12:40:32 ggorjan> %-------------------------------------------------------------------------- @@ -23,7 +23,7 @@ write.fwf(x, file="", append=FALSE, quote=FALSE, sep=" ", na="", rownames=FALSE, colnames=TRUE, rowCol=NULL, justify="left", formatInfo=FALSE, quoteInfo=TRUE, width=NULL, eol="\n", - qmethod=c("escape", "double"), \dots) + qmethod=c("escape", "double"), scientific=TRUE, \dots) } @@ -54,6 +54,8 @@ '"escape"' (default), in which case the quote character is escaped in C style by a backslash, or '"double"', in which case it is doubled. You can specify just the initial letter.} + \item{scientific}{logical, if TRUE, allow numeric values to be + formatted using scientific notation.} \item{\dots}{further arguments to \code{\link{format.info}} and \code{\link{format}} } @@ -61,10 +63,8 @@ \details{ -*F*ixed *w*idth *f*ormat is not used widely anymore. Use some other -format (say *c*omma *s*eparated *v*alues; see \code{\link{read.csv}}) if -you can. However, if you need fixed width format then \code{write.fwf} -can help you. +While *F*ixed *w*idth *f*ormat is no longer widely used, it remains +common in some disciplines. Output is similar to \code{print(x)} or \code{format(x)}. Formatting is done completely by \code{\link{format}} on a column basis. Columns in @@ -217,15 +217,22 @@ ## Force wider columns write.fwf(x=testData[, 1:5], width=20) + ## Show effect of 'scienfic' option + testData$num3 <- testData$num3 * 1e8 + write.fwf(testData, scientific=TRUE) + write.fwf(testData, scientific=FALSE) + testData$num3 <- testData$num3 / 1e8 + ## Write to file and report format and fixed width information file <- tempfile() formatInfo <- write.fwf(x=testData, file=file, formatInfo=TRUE) + formatInfo ## Read exported data back to R (note +1 due to separator) ## ... without header read.fwf(file=file, widths=formatInfo$width + 1, header=FALSE, skip=1, strip.white=TRUE) - + ## ... with header - via postimport modfication tmp <- read.fwf(file=file, widths=formatInfo$width + 1, skip=1, strip.white=TRUE) diff -Nru gdata-2.13.3/MD5 gdata-2.17.0/MD5 --- gdata-2.13.3/MD5 2014-04-06 06:00:49.000000000 +0000 +++ gdata-2.17.0/MD5 2015-07-04 07:51:58.000000000 +0000 @@ -1,11 +1,8 @@ -17f7c7f2a632f33505b7fa7436c018fc *ChangeLog -25a90c79f7e1fc0249a402d727ca2654 *DESCRIPTION +36a8c226fb2da48182140b8c2ccd925c *DESCRIPTION 905fe9c5be6e143737163bc6317e6640 *INSTALL -379df67a91f590d577221ce1002faed1 *NAMESPACE -7be64b29e9fe507512098c4f37595570 *NEWS +1383580c183d48967038864bca34c604 *NAMESPACE 92e3ca5e31d594044b8325a441142c37 *R/Args.R 94976a0bed5195b50511e200d1711280 *R/ConvertMedUnits.R -25491d8b971cbcb3a8594bb7bcaf5d07 *R/aggregate.table.R 38de1344cd5bc79f32a0b42e48b43965 *R/ans.R 78e0c21cf9e4693553a4174d9d3b3c80 *R/bindData.R df4bed53c71599dde15cbf23b4ca645a *R/case.R @@ -17,39 +14,42 @@ 3896b0c9e1e81f87adb9c876f3ecfbda *R/elem.R 0388011f483caa3314a0688a376f7cc5 *R/env.R 7f43c48b182d910961f643876fefbdf9 *R/findPerl.R +d3504262ff8d418a947fe67b33f9a188 *R/first.R 4f9c6613afb87d8360ea897bbc485fe7 *R/frameApply.R d6474a86ab986d0cbcc8712797bbb57b *R/getDateTimeParts.R -a4f086ff4289d532ac61ca2ecc5a8862 *R/installXLSXsupport.R +de896d4d3f1a2e520546d9bad8de34e0 *R/humanReadable.R +773a36e322ff8193f683a52d7027ee20 *R/installXLSXsupport.R 037266e58fb3a611b3a56bb09c898abd *R/interleave.R e9594e1749df0f487eaab95db4253e59 *R/is.what.R 67c1d25af3bb35db744d5534991d3b20 *R/keep.R +b7b1031b972faf2efe7445fb5f396132 *R/left.R b8c1e8dbe508af1afa208883503679ec *R/ll.R b75ac1b645046c8028d8014de255bd25 *R/ls.funs.R -7b718035271b60738818f9973fc656fa *R/mapLevels.R +c88c8f75673c31e0f04a8799a91d1f60 *R/mapLevels.R e7d2246f66781fe99981b2dd083dd6cb *R/matchcols.R afe62c0075aaa73974eabad0c53cf68c *R/nPairs.R 4bb20d225902c5b0a36cbb36a14f85f7 *R/nobs.R -eca2d4b7165eb8ae97e0944284120cc9 *R/object.size.R +1169ce3d329eb62aa51b036df6b24a5b *R/object.size.R c3c6e74c9238d0b99b74c09cf76b154d *R/onAttach.R 53d3ccd68f0b4b5d3e2c27d7bfaedc17 *R/read.xls.R aaace07c7a900ddec695220ad10e0d14 *R/rename.vars.R -8dbe70d52ae3d60a07aa928fc3c62413 *R/reorder.R +54fa890d6dea94a2a0a70e9a568030be *R/reorder.R cef4f8eb74136397feee111cf921676f *R/resample.R f126721102aa7f6d258e74bf6215b831 *R/sheetCount.R dffd0684af87ed05ae550eab75f0787c *R/startsWith.R -3091b03c730a8c96f8f37602315f5b42 *R/trim.R +6ff7e70b153cf189af5f517b5df071a1 *R/trim.R 05f7763f8efeef44932e4c47cfc091ff *R/trimSum.R cccb187cbc78989f5c98633224e7d01e *R/unknown.R 0c763fce55062857b133aebac8695d8c *R/unmatrix.R -d124821046808c5e8492a6db12ac0be4 *R/upperTriangle.R +24c7667dffcef1d6e327f6748a8c7bdc *R/upperTriangle.R 5a0dcdddde5d9c1ec0d215d12f323500 *R/wideByFactor.R -a568b5b2ffcd3552c2ccf06d17e88d01 *R/write.fwf.R +7fb8a64b8ed6279c97b6b38b9be73072 *R/write.fwf.R 41c99f4c80f3c613c8173f93ec9c3bc0 *R/xls2sep.R 84c93b4e26e20d6ff792637f41c71df3 *R/xlsFormats.R -8392400aabc0fd94a90a3e37b479cdba *build/vignette.rds +5f91f515b5ce0099fb8f38c82077bdea *build/vignette.rds 494447a9a3b7a389e79a556a1c356caa *data/MedUnits.rda -17f7c7f2a632f33505b7fa7436c018fc *inst/ChangeLog -7be64b29e9fe507512098c4f37595570 *inst/NEWS +987f0a271d337d959d2cb705c2c522a4 *inst/ChangeLog +c449f3a8a7472e85450b46bf30440206 *inst/NEWS ac512b1ebd4d71ac96b2a4d5288d53cb *inst/bin/xls2csv ce0b4437c51faccb3595d986e8acae80 *inst/bin/xls2csv.bat a7982b90f82857e34a253df2be42d7c1 *inst/doc/Rnews.sty @@ -57,10 +57,10 @@ f1dc90111b7898b5944c1f67abec00a2 *inst/doc/gregmisc.tex b19ba078add1b84a300ae1adb5167567 *inst/doc/mapLevels.R afcc7e1ba12e2aab12a4349fc8470d08 *inst/doc/mapLevels.Rnw -18f86f347e7cb2a3a2b04d5c7b605ca5 *inst/doc/mapLevels.pdf +c790025817a818cec1e70377b9745f97 *inst/doc/mapLevels.pdf 788f58d8791841c0dd0a9bddfa28b8fe *inst/doc/unknown.R a968a07310286934daaea108e3f915f4 *inst/doc/unknown.Rnw -11315bfa6580f66f21115f08d114a172 *inst/doc/unknown.pdf +de4e2b52d3466be1dbf1cd478bc50d87 *inst/doc/unknown.pdf 3622c5d29d09f1a179211f22acf6cdef *inst/perl/Archive/README-Archive-Zip 013677fabc8a49480cca5c10d67dd850 *inst/perl/Archive/Zip.pm da56a4326657fda95d0de93c65ed4006 *inst/perl/Archive/Zip/Archive.pm @@ -75,6 +75,9 @@ 5b969994e19eef9b0fda0c756dd529ef *inst/perl/Archive/Zip/StringMember.pm a0680f49434e681325498f3d0ce1147f *inst/perl/Archive/Zip/Tree.pm 5ad94e7c07432859fc85cec9b215b1a1 *inst/perl/Archive/Zip/ZipFileMember.pm +a12b3df60b1790a375e98cd7e11526d9 *inst/perl/Crypt/RC4.pm +050d359c44120bd9262cd61b9a773cd6 *inst/perl/Digest/Perl/MD5.pm +dfc0b868e0becf87d19a52c24740e5e0 *inst/perl/Graphics/ColorUtils.pm f8109a53128f172d5199998a0774a982 *inst/perl/IO/AtomicFile.pm cb8bf30e73340e4eba233c51dd8b2f34 *inst/perl/IO/InnerFile.pm 5886a657d7e49b133d23f7b2dbe30c21 *inst/perl/IO/Lines.pm @@ -86,40 +89,46 @@ 3669bd450d4fc4e6b883fcd7ad604caf *inst/perl/IO/WrapTie.pm 75749fd752f9b91652bcc147694f00a1 *inst/perl/OLE/README-OLE-Storage_Lite bc2eb29f789cb0c16619b5d88e6f6410 *inst/perl/OLE/Storage_Lite.pm -2120c2a09e745f340014e2847812bcb9 *inst/perl/Spreadsheet/ParseExcel.pm -66cc990f8cf7dcc9ffc145f8e79e226d *inst/perl/Spreadsheet/ParseExcel/Cell.pm -ca067073e60f54322c42f1f697ca74e0 *inst/perl/Spreadsheet/ParseExcel/Dump.pm -e91db20e75505374857f2eb64474a9b3 *inst/perl/Spreadsheet/ParseExcel/FmtDefault.pm -ac8dad0ae1b3fbc2dc45dd0c32d94a8c *inst/perl/Spreadsheet/ParseExcel/FmtJapan.pm -57d3b77da3e011dd2c4b528ecbb32423 *inst/perl/Spreadsheet/ParseExcel/FmtJapan2.pm -04ef4ce775c5af18b3bf820ebd10c41b *inst/perl/Spreadsheet/ParseExcel/FmtUnicode.pm -dc6d43df24f7bdf84ea100f4fbd48717 *inst/perl/Spreadsheet/ParseExcel/Font.pm -a66b33ae7c43dd18f9ac8f16005fedb7 *inst/perl/Spreadsheet/ParseExcel/Format.pm -65807f8d9ef5542a36210b10ee3f1e3c *inst/perl/Spreadsheet/ParseExcel/SaveParser.pm -7c66383e6456e4bf274ecd32345429b9 *inst/perl/Spreadsheet/ParseExcel/SaveParser/Workbook.pm -8e4ee9fc71392d04c1a1a4553b6f580e *inst/perl/Spreadsheet/ParseExcel/SaveParser/Worksheet.pm -ff06c50a267369ebdcb35bb500f1b965 *inst/perl/Spreadsheet/ParseExcel/Utility.pm -4245f158cab85cac7d510d71c29cf3df *inst/perl/Spreadsheet/ParseExcel/Workbook.pm -ec1611346621e6f90510acb619f5252a *inst/perl/Spreadsheet/ParseExcel/Worksheet.pm +ae9cde51f8840b6299d510ddb4360591 *inst/perl/Spreadsheet/ParseExcel.pm +24a716293e90c22e90e53395a14fcb28 *inst/perl/Spreadsheet/ParseExcel/Cell.pm +1abd6d27404bd3ce1ea077bdc647956d *inst/perl/Spreadsheet/ParseExcel/Dump.pm +82f4009b80841e82942de379549527a3 *inst/perl/Spreadsheet/ParseExcel/FmtDefault.pm +efa4e5809ddb4d7041093e8115ac50d0 *inst/perl/Spreadsheet/ParseExcel/FmtJapan.pm +2b155083f756a684723fe400966ca944 *inst/perl/Spreadsheet/ParseExcel/FmtJapan2.pm +d6eba6e2c95f108a1aac09a42e0fb76c *inst/perl/Spreadsheet/ParseExcel/FmtUnicode.pm +6b8027d0201f9e69d2fb44a3846486cf *inst/perl/Spreadsheet/ParseExcel/Font.pm +dc2fcccd7889f61bf96a462a0e26ec7c *inst/perl/Spreadsheet/ParseExcel/Format.pm +797ff88759790280da306ad8fa889c1e *inst/perl/Spreadsheet/ParseExcel/SaveParser.pm +f4d6c7214ff3ac8651710960b57c992a *inst/perl/Spreadsheet/ParseExcel/SaveParser/Workbook.pm +42a270a338246bb0489cb787f538c8a4 *inst/perl/Spreadsheet/ParseExcel/SaveParser/Worksheet.pm +b05f0f8e84a9ad9fb155af83f2d546e7 *inst/perl/Spreadsheet/ParseExcel/Utility.pm +066d26b4c80257a6016f931e6e8ae098 *inst/perl/Spreadsheet/ParseExcel/Workbook.pm +8b53d89dc8969e9840084fc34524bc55 *inst/perl/Spreadsheet/ParseExcel/Worksheet.pm +0209fe512b8c884afc8000c057723a2f *inst/perl/Spreadsheet/ParseXLSX.pm c9b8eab5a257c27463c22af1316e7241 *inst/perl/Spreadsheet/README-ParseExcel 359fb41631453c30b1c8341786d00195 *inst/perl/Spreadsheet/README-XLS -2534020557d8bfced5c2471cc74cd364 *inst/perl/Spreadsheet/XLSX.pm -d1079689d1f8f016913714bc9b3534d1 *inst/perl/Spreadsheet/XLSX/Fmt2007.pm -5e9b67c572312470f95ef4470a030adb *inst/perl/Spreadsheet/XLSX/Utility2007.pm 441b297006e72c914e99851da06d4826 *inst/perl/VERSIONS -694c5ec63d43bc79613707bd7813dc7f *inst/perl/install_modules.pl -38970d085129a053e44c2fe5f704e80e *inst/perl/module_tools.pl -95fb12c6a78ec327de63e9a04f34775f *inst/perl/sheetCount.pl -95fb12c6a78ec327de63e9a04f34775f *inst/perl/sheetNames.pl -f55aa6f304604c5f1eb96351f0dd9b82 *inst/perl/supportedFormats.pl -84e6c5093222000137198cc67f8f1da8 *inst/perl/xls2csv.pl -84e6c5093222000137198cc67f8f1da8 *inst/perl/xls2tab.pl -84e6c5093222000137198cc67f8f1da8 *inst/perl/xls2tsv.pl -59166d9d1e10ea9d544aad1d1a4ed978 *inst/xls/ExampleExcelFile.xls -59f44d54c2c09ee757af7b6724dc9d63 *inst/xls/ExampleExcelFile.xlsx +dee41d67b156f0f146020ee91157ac56 *inst/perl/XML/Twig.pm +41d922f764505fb973db5f098ece6c44 *inst/perl/XML/Twig/XPath.pm +b71548d8785cc55810b5a7d903c52012 *inst/perl/install_modules.pl +b0ff06837bf24d17a67e4da5431c3fb9 *inst/perl/module_tools.pl +44dd4baf6c1ef3999708143f3ab007fd *inst/perl/sheetCount.pl +44dd4baf6c1ef3999708143f3ab007fd *inst/perl/sheetNames.pl +f11614dea00e704edd1582714d1792e2 *inst/perl/supportedFormats.pl +4559c6f484b4e25e5cf037efef73c930 *inst/perl/xls2csv.pl +4559c6f484b4e25e5cf037efef73c930 *inst/perl/xls2tab.pl +4559c6f484b4e25e5cf037efef73c930 *inst/perl/xls2tsv.pl +799008428d5dab63e1bde17859cff753 *inst/xls/ExampleExcelFile.xls +88d5db30d66db593a854e441fcd79fca *inst/xls/ExampleExcelFile.xlsx +beadf509a237ee40d483bd0ac09672d9 *inst/xls/ExampleExcelFile_1900.xls +bdc103a6d2e0e5825c19add38ad2770b *inst/xls/ExampleExcelFile_1900.xlsx +8cfb85e7bfdc636d9b4bfb5dd251b41e *inst/xls/ExampleExcelFile_1904.xls +c2cc0620d5e325d16db0fab03afdba9e *inst/xls/ExampleExcelFile_1904.xlsx 7c16d3cfd37123f3c321c12a92b9269a *inst/xls/iris.xls 8a0467a49bfb791295925cb6a372b1ff *inst/xls/latin-1.xls 36e751188a4e3d37ce3be57d2152922a *inst/xls/latin-1.xlsx +a8cf07872660e85dab41367e2b4f08e5 *inst/xls/wide.xls +47183196217c8b121f88bfd588beffed *inst/xls/wide.xlsx 24a1020fb457c398c620457ad114e245 *man/Args.Rd b0dec88638d111fb8b0c75ebfd99cdfd *man/ConvertMedUnits.Rd 673f2150582676c574a306697b29ffa5 *man/MedUnits.Rd @@ -133,25 +142,27 @@ a471e3c2a2b1ca5550a1822d5620e848 *man/duplicated2.Rd 28b102aeb6f3c62fe6b3b40fefa4c005 *man/elem.Rd e45e3959608492f8e12298d221e605e3 *man/env.Rd +80c283bd90b24dc91a6e8216a031d733 *man/first.Rd 73aeb6a00e393012dfc4fb1e0b8fc15a *man/frameApply.Rd dc8a3653f3c70778ccce2d926194adce *man/gdata-defunct.Rd 34cfa7a16878f7d2032b49f350eec4a5 *man/gdata-package.Rd 38580f70b4b3af84ebfa4b952dd7021b *man/getDateTimePart.Rd -eb90a75f6e6d0171486d3a96626cf04b *man/humanReadable.Rd +76c13487780d8ea770544678350e3f17 *man/humanReadable.Rd 6beab4e8b711110199599f8427d1d042 *man/installXLSXsupport.Rd 26bb8febce31195f8efcf071270913bc *man/interleave.Rd 0d70b8cd533a830a68103355b1054ec5 *man/is.what.Rd 8c50e81caf14aebb11d908fbcc9fe2de *man/keep.Rd +c9e910926112da9792065043cec7d46d *man/left.Rd 4bfbaf0835fff3cbc3ba8f17f9823bfb *man/ll.Rd dfe069423abb32eaed74b2daad0a56d8 *man/ls.funs.Rd 3723cf974f55156ced750e3235445f1b *man/mapLevels.Rd 3ca3aeaf85340d25fc36c6a5275fce2c *man/matchcols.Rd 4789e9c9a034bc5665d93c80579729ef *man/nPairs.Rd 4e3ba1601ecb171596b609516d2e8911 *man/nobs.Rd -67467a836f6e35a897d6bee4d0a7808d *man/object.size.Rd +6604b93792d11b827aaa6c40c9a9cb62 *man/object.size.Rd 2ad3d3570252d4954bdf4d81ea3404fa *man/read.xls.Rd b73a198509b4fdcb4a24a85909309532 *man/rename.vars.Rd -dce038a56263e98621c3715f0aefecd3 *man/reorder.Rd +da64c27965060d0f35bed084a416a57a *man/reorder.Rd fc28b1b680997fd8ff2ab73478db4872 *man/resample.Rd 55d4019112a5759791610fd48c20d4b3 *man/sheetCount.Rd 1a3958cb8dfc8a3d50d73e51bd280a08 *man/startsWith.Rd @@ -159,16 +170,20 @@ 347e8e1afc135b4ce6f5f3a7face76d5 *man/trimSum.Rd 4f5e0665c2c046b93f45963387b7d44f *man/unknown.Rd 5b789bc21ee7f46f8a9b138f1ed36829 *man/unmatrix.Rd -9778a0a2d069cddda0f2e821143d691e *man/upperTriangle.Rd +7427fd1c31684c2392095c99c8fc7006 *man/upperTriangle.Rd ad219282ec6913083b82073691923f9b *man/wideByFactor.Rd -56d52a59a9c4f5132d5ae69673823ae8 *man/write.fwf.Rd +33f5856b0960a91d03807b781e664704 *man/write.fwf.Rd 8a9c1fe9d0316d0b98e6d353c2b7a6cf *man/xlsFormats.Rd 64fc1cde149ab7f61c266fdb295a6404 *tests/runRUnitTests.R -10fe383026608ee1cf2c8f1b70a02c5b *tests/test.read.xls.R -b829acdc86095be7759e0d001b8e9599 *tests/test.read.xls.Rout.save +89f2fc0a5b6dd6ff34fa2facd5d36127 *tests/test.humanReadable.R +fb097d7209dc5e20b33fa46afe861ac9 *tests/test.humanReadable.Rout.save +8d734967558d8d545de947ddd4ba06ac *tests/test.read.xls.R +3d44dd3a3a4a4fabd4c89c5c18d43644 *tests/test.read.xls.Rout.save +db19f080b3ed7525389cecf47481409f *tests/test.reorder.factor.R +78c0dd82c14a6d9d668ffb2fa775e635 *tests/test.reorder.factor.Rout.save dee3232474b92bcdf1ad75ca31080792 *tests/test.write.fwf.eol.R b32b0eb85790d71ea6025ae5eca71fb1 *tests/tests.write.fwf.R -dba6d4c18936f97e03225af5be4743ed *tests/tests.write.fwf.Rout.save +a604f7945af6600559d693d1db3abecc *tests/tests.write.fwf.Rout.save ed871fe534197367139b63b6c8309396 *tests/unitTests/Makefile 52c3dc4a6188f8db93bde320cb6bb5ed *tests/unitTests/report.html 11154df5a069efad335f1a9808b6cc01 *tests/unitTests/report.txt @@ -183,7 +198,7 @@ 42330b4f7f6bd1cd335f59088d6bf282 *tests/unitTests/runit.trimSum.R 80c6bc219e067e6c933b61dc3b3042c1 *tests/unitTests/runit.unknown.R 07c0f9fc38612b196f2d7449c133fde2 *tests/unitTests/runit.wideByFactor.R -095012d02d40b8c33c37e1c307ac19d0 *tests/unitTests/runit.write.fwf.R +8bd376ab7034b5f9016caff11eecbb92 *tests/unitTests/runit.write.fwf.R a7982b90f82857e34a253df2be42d7c1 *vignettes/Rnews.sty afcc7e1ba12e2aab12a4349fc8470d08 *vignettes/mapLevels.Rnw a968a07310286934daaea108e3f915f4 *vignettes/unknown.Rnw diff -Nru gdata-2.13.3/NAMESPACE gdata-2.17.0/NAMESPACE --- gdata-2.13.3/NAMESPACE 2014-04-05 01:30:44.000000000 +0000 +++ gdata-2.17.0/NAMESPACE 2015-07-03 19:22:18.000000000 +0000 @@ -3,7 +3,6 @@ .onAttach, ans, Args, - aggregate.table, bindData, case, cbindX, @@ -14,11 +13,14 @@ duplicated2, elem, env, + first, frameApply, installXLSXsupport, interleave, is.what, keep, + last, + left, ll, ls.funs, lowerTriangle, @@ -31,6 +33,7 @@ remove.vars, reorder.factor, resample, + right, sheetCount, sheetNames, startsWith, @@ -48,7 +51,7 @@ xlsFormats, ## Object size stuff - object.size, as.object_size, is.object_size, humanReadable, + object.size, as.object_sizes, is.object_sizes, humanReadable, ## getDateTime stuff getYear, getMonth, getDay, getHour, getMin, getSec, @@ -63,6 +66,8 @@ importFrom(stats, reorder) importFrom(stats, nobs) importFrom(gtools, mixedsort) +importFrom(methods, is) +importFrom(utils, data, download.file, head, read.csv, read.delim, read.table, tail, write.table) S3method(reorder, factor) @@ -125,8 +130,9 @@ S3method(nobs, lm) # now provided by stats package ## Object size stuff -S3method(print, object_size) -S3method(c, object_size) +S3method(c, object_sizes) +S3method(format, object_sizes) +S3method(print, object_sizes) ## unknown stuff S3method(isUnknown, default) @@ -151,3 +157,11 @@ S3method(trim, factor) S3method(trim, list) S3method(trim, data.frame) + +## left, right +S3method(left, data.frame) +S3method(left, matrix) +S3method(right, data.frame) +S3method(right, matrix) + + diff -Nru gdata-2.13.3/NEWS gdata-2.17.0/NEWS --- gdata-2.13.3/NEWS 2014-04-05 18:41:12.000000000 +0000 +++ gdata-2.17.0/NEWS 1970-01-01 00:00:00.000000000 +0000 @@ -1,529 +0,0 @@ -Changes in 2.13.3 (2014-04-04) ------------------------------- - -Bug Fixes - -- Unit tests were incorrectly checking for equality of optional POSIXlt - components. (Bug reported by Brian Ripley). - -Other Changes - -- 'aggregate.table' is now defunct. See '?gdata-defunct' for details. - -- Unit tests and vignettes now follow R standard practice. - -- Minor changes to clean up R CMD check warnings. - -Changes in 2.13.2 (2013-06-28) ------------------------------- - -Enhancements: - -- Simplify ll() by converting a passed list to an environment, - avoiding the need for special casing and the use of attach/detach. - -- Working of deprecation warning message in aggregate.table clarified. - -Changes in 2.13.1 (2013-03-24) ------------------------------- - -Enhancements: - -- Replaced calls to depreciated function ".path.package" with the new - public function "path.package". - - -Changes in 2.13.0 (2012-09-20) ------------------------------ - -New features: - -- New 'duplicated2' function which returns TRUE for *all* elements - that are duplicated, including the first, contributed by Liviu - Andronic. This differs from 'duplicated', which only returns the - second and following (second-to last and previous when - 'fromLast=TRUE') duplicate elements. - -- New 'ans' functon to return the value of the last evaluated - top-level function (a convenience function for accessing - .Last.value), contributed by Liviu Andonic. - -Bug Fixes: - -- On windows, warning messages printed to stdout by perl were being - included in the return value from 'system', resulting in errors in - 'sheetCount' and 'sheetNames'. Corrected. - -- The 'MedUnits' column names 'SIUnits' and 'ConventionalUnits' were - reversed and misspelled. - - -Changes in 2.12.0 (2012-09-12) ------------------------------- - -Other Changes: - -- 'stats::aggregate' was made into a generic on 27-Jan-2010, so that - attempting to call 'aggregate' on a 'table' object will now - incorrectly call 'aggregate.table'. Since 'aggregate.table' can be - replaced by a call to tapply using two index vectors, e.g. - aggregate.table(x, by1=a, by2=b, mean) - can be replaced by - tapply(x, INDEX=list(a, b), FUN=mean), - the 'aggregate.table' function will now display a warning that it - is depreciated and recommending the equivalent call to tapply. It - will be removed entirely in a future version of gdata. - -Changes in 2.11.1 (2012-08-22) ------------------------------- - -Enhancements: - -- read.xls() now supports fileEncoding argument to allow non-ascii - encoded data to be handled. See the manual page for an example. - -Bug Fixes: - -- The perl script utilized by read.xls() was incorrectly appending a - space character at the end of each line, causing problems with - character and NA entries in the final column. - - -Changes in 2.11.0 (2012-06-18) ------------------------------- - -New Features: - -- read.xls() and supporting functions now allow blank lines to be - preserved, rather than skipped, by supplying the argument - "blank.lines.skip=FALSE". The underlying perl function has been - extended to suppor this via an optional "-s" argument which, when - present, *preserves* blank lines during the conversion. (The - default behavior remains unchanged.) - -Other Changes: - -- Add SystemRequirements field specifying that perl is necessary for - gdata to function fully. - - -Changes in 2.10.6 (2012-06-12) ------------------------------- - -Bug fixes: - -- gdata::nobs.default() needs to handle logical vectors in addition to - numeric vectors. - -Changes in 2.10.{3,4,5} (2012-06-08) ------------------------------------- - -Bug fixes: - -- Mark example for installXLSsupport() as dontrun so R CMD check won't - fail on systems where PERL is not fully functional. - -- Correct name of installXLSsupport() in tests/test.read.xls.R. - -Other Changes: - -- Add dependency on R 2.13.0, since that is when stats::nobs appeared. - - -Changes in 2.10.2 (2012-06-06) ---------------------------------------- - -Bug fixes: - -- Fix issues in nobs.default identified in testing with the gmodels package. - - -Changes in 2.10.1 (2012-06-06) ------------------------------- - -Bug fixes: - -- Undo removal of 'nobs' and 'nobs.lm'. Instead define aliases for - 'nobs' and 'nobs.lm' to support backward compatibility for packages - depending on gdata. - - -Changes in 2.10.0 (2012-06-05) ------------------------------- - -New features: - -- New ls.funs() function to list all objects of class function in the - specified environment. - -- New startsWith() function to determine if a string "starts with" the - specified characters. - - -Enhancements: - -- Add 'na.strings' argument to read.xls() to convert Excel's '#DIV/0!' to NA. - - -Bug fixes: - -- Correct various R CMD check warnings - - -Other changes: - -- Base S3 method for nobs() and nobs.lm() method removed since these - are now provided in the stats package. - - -Changes in 2.9.0 (2011-09-30) ------------------------------ - -New features: - -- Add centerText() function to center text strings for a specified - width. - -- Add case() function, a vectorized variant of the base::switch() - function, which is useful for converting numeric codes into factors. - -Enhancements: - -- Minor improvements to xls2csv() man page. - -CHANGES IN 2.8.1 (2011-04-15) ------------------------------ - -Enhancements: - -- nPairs() gains a summary method that shows how many times each variable - is known, while the other variable of a pair is not - -Bug fixes: - -- Fix errors on windows when R or Perl install path includes spaces by properly quoting the path. - - -CHANGES IN 2.8.1 (2010-11-12) ------------------------------ - -Enhancements: - -- Minor improvement to Args(), read.xls() man page. - -Bug fixes: - -- Modify write.fwf() to capture and pass on additional arguments for - write.table(). This resolves a bug reported by Jan Wijffels. - -- Modify xls2sep.R to avoid use of file.access() which is unreliable - on Windows network shares. - - -CHANGES IN 2.8.0 (2010-04-03) ------------------------------ - -Enhancements: - -- When loaded, gtools (via an .onAttach() function) now checks: - 1) if perl is available - 2) whether the perl libraries for XLS support are available - 3) whether the perl libraries for XLSX support are available - - If perl is not available, an appropriate warning message is displayed. - - If necessary perl libraries are not available, a warning message is - displayed, as is a message suggesting the user run the (new) - installXLSXsupport() function to attempt to install the necessary - perl libraries. - -- The function installXLSXsupport() has been provided to install the - binary perl modules that read.xls needs to support Excel 2007+ - 'XLSX' files. - - -CHANGES IN 2.7.3 (2010-04-02) ------------------------------ - -Enhancements: - -- New xlsFormats() command to determine which Excel formats are - supported (XLS, XLSX). - -Bug Fixes: - -- No longer attempt to install perl modules Compress::Raw::Zlib and - Spreadsheet::XLSX at build/compile time. This should resolve recent - build issues, particularly on Windows. - -- All perl code can now operate (but generate warnings) when perl modules Compress::Raw::Zlib and - Spreadsheet::XLSX when are not installed. - -- Also update Greg's email address. - -CHANGES IN 2.7.1 (2010-02-19) ------------------------------ - -Enhancements: - -- on Windows attempts to locate ActiveState perl if perl= not specified and - Rtools perl would have otherwise been used in read.xls and other perl - dependent functions. - -CHANGES IN 2.7.0 (2010-01-25) ------------------------------ - -Bug Fixes: - -- Fix building of Perl libraries on Win32 - - -CHANGES IN 2.7.0 (2010-01-25) ------------------------------ - -Enhancements: - -- read.xls() now supports Excel 2007 'xlsx' files. - -- read.xls() now allows specification of worksheet by name - -- read.xls() now supports ftp URLs. - -- Improved ll() so user can limit output to specified classes - - - -New Functions: - -- sheetCount() and sheetNames() to determine the number and names of - worksheets in an Excel file, respectively. - -Bug Fixes: - -- Fix formatting warning in frameApply(). - -- Resolve crash of "ll(.GlobalEnv)" - -- - -CHANGES IN 2.6.1 (2009-07-15) ------------------------------ - -Bug Fixes - -- Modify unit tests to avoid issues related to time zones. - - -CHANGES IN 2.6.0 (2009-07-15) ------------------------------ - -Bug Fixes - -- Correct minor typos & issues in man pages for write.fwf(), - resample() (Greg Warnes) - -- Correct calculation of object sizes in env() and ll() (Gregor Gorjanc) - -New Features - -- Add support for using tab for field separator during translation - from xls format in read.xls (Greg Warnes) - -- Enhanced function object.size that returns the size of multiple - objects. There is also a handy print method that can print size of - an object in "human readable" format when - options(humanReadable=TRUE) - or - print(object.size(x), humanReadable=TRUE). - (Gregor Gorjanc) - -- New function wideByFactor that reshapes given dataset by a given - factor - it creates a "multivariate" data.frame. (Gregor Gorjanc) - -- New function nPairs that gives the number of variable pairs in a - data.frame or a matrix. (Gregor Gorjanc) - -- New functions getYear, getMonth, getDay, getHour, getMin, and getSec - for extracting the date/time parts from objects of a date/time - class. (Gregor Gorjanc) - -- New function bindData that binds two data frames into a multivariate - data frame in a different way than merge. (Gregor Gorjanc) - -Other Changes - -- Correct Greg's email address - - -CHANGES IN 2.5.0 ----------------- - -- New function .runRUnitTestsGdata that enables run of all RUnit tests during - the R CMD check as well as directly from within R. - -- Enhanced function object.size that returns the size of multiple objects. There - is also a handy print method that can print size of an object in "human readable" - format when options(humanReadable=TRUE) or print(x, humanReadable=TRUE). - -- New function bindData that binds two data frames into a multivariate data frame - in a different way than merge. - -- New function wideByFactor that reshapes given dataset by a given factor - - it creates a "multivariate" data.frame. - -- New functions getYear, getMonth, getDay, getHour, getMin, and getSec for - extracting the date/time parts from objects of a date/time class. - -- New function nPairs that gives the number of variable pairs in a data.frame - or a matrix. - -- New function trimSum that sums trimmed values. - -- New function cbindX that can bind objects with different number of rows. - -- write.fwf gains the width argument. The value for unknown can increase or - decrease the width of the columns. Additional tests and documentation fixes. - -CHANGES IN 2.4.2 (2008-05-11) ------------------------------ - -- Enhancements and bug fixes for read.xls() and xls2csv(): - - - More informative log messages when verbose=TRUE - - - File paths containing spaces or other non-traditional characters - are now properly handled - - - Better error messages, particularly when perl fails to generate - an output .csv file. - - - The 'shortcut' character "~" (meaning user's home directory) is - now properly handled in file paths. - - - XLS files created by OpenOffice are now properly handled. Thanks to - Robert Burns for pointing out the patch - (http://rt.cpan.org/Public/Bug/Display.html?id=7206) - -CHANGES IN 2.4.1 (2008-03-24) ------------------------------ - -- Update perl libraries needed by xls2csv() and read.xls() - to latest available versions on CRAN. - -- Add read.xls() to exported function list - -- Correct iris.xls example file. It didn't contain the complete - & properly formatted iris data set. Fixed. - -- Fix typo in win32 example for read.xls() - -CHANGES IN 2.4.0 (2008-01-30) ------------------------------ - -- The keep() function now includes an 'all' argument to specify how - objects with names starting with '.' are handled. - -- keep() now shows an informative warning message when a requested - object does not exist - -- New vignette "Mapping Levels of a Factor" describing the use of - mapLevels(). - -- New vignette "Working with Unknown Values" describing the use of - isUnknown() and unknownToNA(). - -- Several enhancements to read.xls() (thanks to Gabor Grothendieck): - - - New function xls2csv(), which handles converting an xls file - to a csv file and returns a connection to the - temporary csv file - - - xls2csv() and read.xls() both allow a file or a url to be specified - - - read.xls() has a new 'pattern' argument which, if supplied, - will ignore everything prior to the first line in th csv file - that matches the pattern. This is typically used if there - are a variable number of comment lines prior to the header - in which case one can specify one of the column - headings as the pattern. read.xls should - be compatible with the old read.xls. - -- Minor fixes to drop.levels(), is.what(). - -- Implementation of unit tests for most functions. - -CHANGES IN 2.3.1 (2006-10-29) ------------------------------ - -- Arguments as well as their position of reorder.factor have been changed - to conform with reorder.factor method in stats package, due to collision - bug. Argument 'make.ordered' is now 'order' and old argument 'order' is - now 'new.order'! Therefore, you have to implicitly specify new.order i.e. - - reorder(trt, new.order=c("PLACEBO", "300 MG", "600 MG", "1200 MG")) - -- trim() gains ... argument. - -- Added "unknown" methods for matrices. - -- Added c() method for factors based on mapLevels() functions. - -- Added write.fwf, which writes file in *F*ixed *W*idth *F*ormat. - -CHANGES FROM 2.1.X to 2.3.0 (2006-09-19) ---------------------------------------- - -- Added mapLevels(), which produces a map with information on levels and/or - internal integer codes. Contributed by Gregor Gorjanc. - -- Extended dropLevels() to work on the factors contained in a data - frame, as well as individual factors. - -- Add unknown(), which changes given unknown value to NA and vice - versa. Contributed by Gregor Gorjanc. - -- Extended trim() to handle a variety of data types data.frames, - lists, factors, etc. Code changes contributed by Gregor Gorjanc. - -- Added resample() command that acts like sample() except that it - _always_ samples from the arguments provided, even if only a single - argument is present. This differs from sample() which behaves - differently in this case. - -- Updated my email address. - -CHANGES IN GDATA 2.1.2 ------------------------ - - - Fixed bug in interleave.R - option to covert 1-column matrices to - vector (based on Andrew Burgess's suggestion) - - - Updated Greg and Jim's email adresses - - - ll.R: Suppressed warning message in attach() call. - - - frameApply.Rd, reorder.Rd: Remove explicit loading of - gtools in examples, so that failure to import functions from - gtools gets properly caught by running the examples. - - - upperTriangle.R, man/upperTriangle.Rd: Add functions for - extracting and modifying the upper and lower trianglular components of - matrices. - - - is.what.R: Replaced the "not.using" vector with a more robust - try(get(test)) to find out whether a particular is.* function - returns a logical of length one. - -- DESCRIPTION: Added Suggests field - -- Updated the example in frameApply - - -CHANGES IN GDATA 2.0.8 ------------------------ - - - Added DESCRIPTION and removed DESCRIPTION.in - - - Updated ll.Rd documentation - - - Fixed bug in Args.R, is.what.R, ll.R diff -Nru gdata-2.13.3/R/aggregate.table.R gdata-2.17.0/R/aggregate.table.R --- gdata-2.13.3/R/aggregate.table.R 2014-04-05 13:57:11.000000000 +0000 +++ gdata-2.17.0/R/aggregate.table.R 1970-01-01 00:00:00.000000000 +0000 @@ -1,39 +0,0 @@ -# $Id: aggregate.table.R 1788 2014-04-05 13:57:10Z warnes $ - -aggregate.table <- function(x, by1, by2, FUN=mean, ...) - { - .Defunct( - new=paste( - "tapply(X=", - deparse(substitute(x)), - ", INDEX=list(", - deparse(substitute(by1)), - ", ", - deparse(substitute(by2)), - "), FUN=", - deparse(substitute(FUN)), - if(length(list(...))>0) - { - l <- list(...) - paste(", ", - paste(names(l),"=", - deparse(substitute(...)), - sep="", - collapse=", ") - ) - }, - ")", sep=""), - package="gdata" - ) - } - -## aggregate.table <- function(x, by1, by2, FUN=mean, ... ) -## { -## -## tab <- matrix( nrow=nlevels(by1), ncol=nlevels(by2) ) -## dimnames(tab) <- list(levels(by1),levels(by2)) -## -## for(i in 1:nrow(ag)) -## tab[ as.character(ag[i,1]), as.character(ag[i,2]) ] <- ag[i,3] -## tab -## } diff -Nru gdata-2.13.3/R/first.R gdata-2.17.0/R/first.R --- gdata-2.13.3/R/first.R 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/R/first.R 2015-04-28 02:17:04.000000000 +0000 @@ -0,0 +1,3 @@ +# Simply call 'first' or 'last' with a different default value for 'n'. +first <- function(x, n=1, ...) head(x, n=n, ...) +last <- function(x, n=1, ...) tail(x, n=n, ...) diff -Nru gdata-2.13.3/R/humanReadable.R gdata-2.17.0/R/humanReadable.R --- gdata-2.13.3/R/humanReadable.R 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/R/humanReadable.R 2015-04-25 06:33:47.000000000 +0000 @@ -0,0 +1,88 @@ +humanReadable <- function(x, + units="auto", + standard=c("IEC", "SI", "Unix"), + digits=1, + width=NULL, + sep=" ", + justify = c("right", "left") + ) +{ + ## --- Setup --- + + suffix.SI <- c("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB") + suffix.IEC <- c("B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB") + suffix.Unix <- c("B" , "K", "M", "G", "T", "P", "E", "Z", "Y") + + standard <- match.arg(standard) + if(length(justify)==1) justfy <- c(justify, justify) + + ## --- Functions --- + + .applyHuman <- function(x, base, suffix, digits, width, sep) + { + ## Which suffix should we use? + n <- length(suffix) + i <- pmax(pmin(floor(log(x, base)), n-1),0) + if(!is.finite(i)) i <- 0 + x <- x / base^i + ## Formatting + if(is.null(width)) + ## the same formatting for all + x <- format(round(x=x, digits=digits), nsmall=digits) + else + { + ## similar to ls, du, and df + lenX <- nchar(x) + if(lenX > width) { + digits <- pmax( width - nchar(round(x)) - 1, 0) + } + if(i == 0) digits <- 0 + x <- round(x, digits=digits) + } + c(x, suffix[i+1]) + } + + ## -- Work + + if(any(x < 0)) stop("'x' must be positive") + if(standard == "SI") + { + suffix <- suffix.SI + base <- 10^3 + } + else if (standard=="IEC") + { + suffix <- suffix.IEC + base <- 2^10 + } + else # (standard=="Unix) + { + suffix <- suffix.Unix + base <- 2^10 + } + + if(!missing(units) && units=="bytes") + { + retval <- rbind(x, "bytes") + } + else if(!missing(units) && units!="auto") + { + units <- suffix[match( toupper(units), toupper(suffix) )] + power <- match(units, suffix ) -1 + X <- x/(base^power) + X <- format.default(x=X, digits=digits, nsmall=digits) + retval <- rbind(X, rep(units, length(X))) + } + else + retval <- sapply(X=x, FUN=".applyHuman", base=base, suffix=suffix, + digits=digits, width=width, sep=sep) + + if(all(justify == "none")) + paste(trim(retval[1,]), trim(retval[2,]), sep=sep) + else + paste(format(trim(retval[1,]), justify=justify[1]), + format(trim(retval[2,]), justify=justify[2]), + sep=sep) + +} + diff -Nru gdata-2.13.3/R/installXLSXsupport.R gdata-2.17.0/R/installXLSXsupport.R --- gdata-2.13.3/R/installXLSXsupport.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/installXLSXsupport.R 2015-04-28 21:31:48.000000000 +0000 @@ -7,17 +7,18 @@ findPerl(verbose = verbose) else findPerl(perl, verbose = verbose) - + ## ## directories package.dir <- find.package('gdata') perl.dir <- file.path(package.dir,'perl') + temp.dir <- tempdir() ## ## cmd <- "install_modules.pl" sc <- file.path(perl.dir, cmd) - + ## ## @@ -53,6 +54,6 @@ else { stop("\nUnable to install Perl XLSX support libraries.\n\n") - invisible(FALSE) - } + invisible(FALSE) + } } diff -Nru gdata-2.13.3/R/left.R gdata-2.17.0/R/left.R --- gdata-2.13.3/R/left.R 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/R/left.R 2015-04-28 02:28:27.000000000 +0000 @@ -0,0 +1,38 @@ +left <- function(x, n=6L) UseMethod("left") +right <- function(x, n=6L) UseMethod("left") + +left.data.frame <- function(x, n=6) +{ + stopifnot(length(n) == 1L) + n <- if (n < 0L) + max(ncol(x) + n, 0L) + else min(n, ncol(x)) + x[, seq_len(n), drop = FALSE] +} +left.matrix <- left.data.frame + + +right.data.frame <- function (x, n = 6L, ...) +{ + stopifnot(length(n) == 1L) + ncx <- ncol(x) + n <- if (n < 0L) + max(ncx + n, 0L) + else min(n, ncx) + x[, seq.int(to = ncx, length.out = n), drop = FALSE] +} + +right.matrix <- function (x, n = 6L, addcolnums = TRUE, ...) +{ + stopifnot(length(n) == 1L) + ncx <- ncol(x) + n <- if (n < 0L) + max(ncx + n, 0L) + else min(n, ncx) + sel <- seq.int(to = ncx, length.out = n) + ans <- x[, sel, drop = FALSE] + if (addcolnums && is.null(colnames(x))) + colnames(ans) <- paste0("[", sel, ",]") + ans +} + diff -Nru gdata-2.13.3/R/mapLevels.R gdata-2.17.0/R/mapLevels.R --- gdata-2.13.3/R/mapLevels.R 2014-04-05 18:19:53.000000000 +0000 +++ gdata-2.17.0/R/mapLevels.R 2015-04-29 03:27:54.000000000 +0000 @@ -1,7 +1,7 @@ ### mapLevels.R ###------------------------------------------------------------------------ ### What: Mapping levels -### $Id: mapLevels.R 1797 2014-04-05 18:19:49Z warnes $ +### $Id: mapLevels.R 1991 2015-04-29 03:27:50Z warnes $ ### Time-stamp: <2007-04-26 13:16:18 ggorjan> ###------------------------------------------------------------------------ @@ -300,8 +300,8 @@ ## --- Mapping levels in x --- - char <- all(lapply(value, is.character)) - int <- all(lapply(value, is.integer)) + char <- all(sapply(value, is.character)) + int <- all(sapply(value, is.integer)) if(int) { # codes=TRUE if(is.integer(x)) x <- factor(x) diff -Nru gdata-2.13.3/R/object.size.R gdata-2.17.0/R/object.size.R --- gdata-2.13.3/R/object.size.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/object.size.R 2015-04-25 06:47:06.000000000 +0000 @@ -1,92 +1,93 @@ -### object.size.R ###------------------------------------------------------------------------ ### What: Print object size in human readable format - code -### $Id$ -### Time-stamp: <2008-12-30 08:05:43 ggorjan> ###------------------------------------------------------------------------ - -object.size <- function(...) +object.size <- function(...) { structure(sapply(list(...), utils::object.size), - class=c("object_size", "numeric")) + class=c("object_sizes", "numeric")) } -print.object_size <- function(x, quote=FALSE, humanReadable, ...) -{ - xOrig <- x - if(missing(humanReadable)) { - opt <- getOption("humanReadable") - humanReadable <- ifelse(!is.null(opt), opt, FALSE) - } - if(humanReadable) { - print(humanReadable(x), quote=quote, ...) - } else { - class(x) <- "numeric" - NextMethod() - } - invisible(xOrig) +print.object_sizes <- function(x, + quote=FALSE, + humanReadable=getOption("humanReadable"), + standard="IEC", + units, + digits=1, + width=NULL, + sep=" ", + justify = c("right", "left"), + ...) +{ + print(format(x, + humanReadable=humanReadable, + standard=standard, + units=units, + digits=digits, + width=width, + sep=sep, + justify=justify), + quote=quote, + ...) + + + invisible(x) } -is.object_size <- function(x) inherits(x, what="object_size") - -as.object_size <- function(x) +format.object_sizes <- function(x, + humanReadable=getOption("humanReadable"), + standard="IEC", + units, + digits=1, + width=NULL, + sep=" ", + justify = c("right", "left"), + ...) { - if(!is.numeric(x)) stop("'x' must be numeric/integer") - class(x) <- c("object_size", "numeric") - x + if( !missing(units) ) + { + if (units=="bytes") + paste(x, "bytes") + else + humanReadable(x, + standard=standard, + units=units, + digits=digits, + width=width, + sep=sep, + justify=justify + ) + } + else if( is.null(humanReadable) || humanReadable==FALSE ) + paste(x, "bytes") + else + humanReadable(x, + standard=standard, + units=units, + digits=digits, + width=width, + sep=sep, + justify=justify) + } -c.object_size <- function(..., recursive=FALSE) + + +is.object_sizes <- function(x) inherits(x, what="object_sizes") + +as.object_sizes <- function(x) { - x <- NextMethod() - if(is.numeric(x)) class(x) <- c("object_size", "numeric") + if(!is.numeric(x) || any(x<0)) stop("'x' must be a positive numeric vector") + + class(x) <- c("object_sizes", "numeric") x } -humanReadable <- function(x, standard="SI", digits=1, width=3, sep=" ") +c.object_sizes <- function(..., recursive=FALSE) { - ## --- Setup --- - - if(any(x < 0)) stop("'x' must be positive") - if(standard == "SI") { - suffix <- c("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB") - base <- 1000 - } else { - suffix <- c("B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB") - base <- 1024 - } - - ## --- Apply --- - - .applyHuman <- function(x, base, suffix, digits, width, sep) - { - ## Which suffix should we use? - n <- length(suffix) - for(i in 1:n) { - if(x >= base) { - if(i < n) x <- x / base - } else { - break - } - } - ## Formatting - if(is.null(width)) { ## the same formatting for all - x <- format(round(x=x, digits=digits), nsmall=digits) - } else { ## similar to ls, du, and df - lenX <- nchar(x) - if(lenX > width) { - digitsMy <- width - (lenX - (lenX - (nchar(round(x)) + 1))) - digits <- ifelse(digitsMy > digits, digits, digitsMy) - } - if(i == 1) digits <- 0 - x <- round(x, digits=digits) - } - paste(x, suffix[i], sep=sep) - } - - sapply(X=x, FUN=".applyHuman", base=base, suffix=suffix, digits=digits, - width=width, sep=sep) + x <- NextMethod() + if(is.numeric(x)) class(x) <- c("object_sizes", "numeric") + x } ###------------------------------------------------------------------------ diff -Nru gdata-2.13.3/R/reorder.R gdata-2.17.0/R/reorder.R --- gdata-2.13.3/R/reorder.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/reorder.R 2015-04-28 06:03:14.000000000 +0000 @@ -1,7 +1,3 @@ -# $Id: reorder.R 988 2006-10-29 12:55:08Z ggorjan $ - -# Reorder the levels of a factor. - reorder.factor <- function(x, X, FUN, @@ -12,15 +8,31 @@ { constructor <- if (order) ordered else factor - if (!missing(new.order)) + if(!missing(X) || !missing(FUN)) + { + if(missing(FUN)) FUN <- 'mean' + + ## I would prefer to call stats::reorder.default directly, + ## but it exported from stats, so the relevant code is + ## replicated here: + ## --> + scores <- tapply(X = X, INDEX = x, FUN = FUN, ...) + levels <- names(base::sort(scores, na.last = TRUE)) + if(order) + ans <- ordered(x, levels=levels) + else + ans <- factor(x, levels=levels) + attr(ans, "scores") <- scores + ## <-- + return(ans) + } + else if (!missing(new.order)) { if (is.numeric(new.order)) new.order <- levels(x)[new.order] else new.order <- new.order } - else if (!missing(FUN)) - new.order <- names(sort(tapply(X, x, FUN, ...))) else new.order <- sort(levels(x)) diff -Nru gdata-2.13.3/R/trim.R gdata-2.17.0/R/trim.R --- gdata-2.13.3/R/trim.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/trim.R 2015-04-28 04:30:06.000000000 +0000 @@ -1,5 +1,3 @@ -# $Id: trim.R 1757 2013-12-16 19:58:56Z warnes $ - trim <- function(s, recode.factor=TRUE, ...) UseMethod("trim", s) @@ -19,7 +17,7 @@ if(recode.factor) { dots <- list(x=s, ...) if(is.null(dots$sort)) dots$sort <- sort - s <- do.call(what=reorder.factor, args=dots) + s <- do.call(what="reorder.factor", args=dots) } s } diff -Nru gdata-2.13.3/R/upperTriangle.R gdata-2.17.0/R/upperTriangle.R --- gdata-2.13.3/R/upperTriangle.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/upperTriangle.R 2015-06-29 22:33:46.000000000 +0000 @@ -1,22 +1,42 @@ -upperTriangle <- function(x, diag=FALSE) +upperTriangle <- function(x, diag=FALSE, byrow=FALSE) { - x[upper.tri(x, diag=diag)] + if(byrow) + t(x)[rev(upper.tri(x, diag=diag))] + else + x[upper.tri(x, diag=diag)] } -"upperTriangle<-" <- function(x, diag=FALSE, value) +"upperTriangle<-" <- function(x, diag=FALSE, byrow=FALSE, value) { - x[upper.tri(x, diag=diag)] <- value - x + if(byrow) { + ret <- t(x) + ret[rev(upper.tri(x, diag=diag))] <- value + t(ret) + } + else { + x[upper.tri(x, diag=diag)] <- value + x + } } -lowerTriangle <- function(x, diag=FALSE) +lowerTriangle <- function(x, diag=FALSE, byrow=FALSE) { + if(byrow) + t(x)[rev(lower.tri(x, diag=diag))] + else x[lower.tri(x, diag=diag)] } -"lowerTriangle<-" <- function(x, diag=FALSE, value) +"lowerTriangle<-" <- function(x, diag=FALSE, byrow=FALSE, value) { + if(byrow) { + ret <- t(x) + ret[rev(lower.tri(x, diag=diag))] <- value + t(ret) + } + else { x[lower.tri(x, diag=diag)] <- value x } +} diff -Nru gdata-2.13.3/R/write.fwf.R gdata-2.17.0/R/write.fwf.R --- gdata-2.13.3/R/write.fwf.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/R/write.fwf.R 2015-04-25 16:24:11.000000000 +0000 @@ -1,7 +1,7 @@ ### write.fwf.R ###------------------------------------------------------------------------ ### What: Write fixed width format - code -### $Id: write.fwf.R 1459 2010-11-12 19:08:12Z warnes $ +### $Id: write.fwf.R 1959 2015-04-25 07:56:23Z warnes $ ### Time-stamp: <2008-08-05 12:11:27 ggorjan> ###------------------------------------------------------------------------ @@ -20,21 +20,43 @@ width=NULL, eol="\n", qmethod=c("escape", "double"), + scientific=TRUE, ...) { ## --- Setup --- + dapply <- function(x, FUN, ..., simplify=TRUE) + { + if(is.data.frame(x)) + return(sapply(x, FUN, ..., simplify=simplify)) + else if(is.matrix(x)) + return(apply(x, 2, FUN, ...)) + else + stop("x must be a data.frame or a matrix") + } + if(!(is.data.frame(x) || is.matrix(x))) stop("'x' must be a data.frame or matrix") if(length(na) > 1) stop("only single value can be defined for 'na'") + if(!scientific) + { + option.scipen <- getOption("scipen") + on.exit( function() options("scipen"=option.scipen) ) + options("scipen"=100) + } + + if(rownames) { + x <- as.data.frame(x) x <- cbind(rownames(x), x) rowColVal <- ifelse(!is.null(rowCol), rowCol, "row") colnames(x)[1] <- rowColVal } colnamesMy <- colnames(x) + if(length(colnamesMy)==0) + colnamesMy <- paste( "V", 1:ncol(x), sep="") nRow <- nrow(x) nCol <- length(colnamesMy) @@ -58,22 +80,26 @@ stringsAsFactors=FALSE) ## Which columns are numeric like - isNum <- sapply(x, is.numeric) + isNum <- dapply(x, is.numeric) ## is.numeric picks also Date and POSIXt - isNum <- isNum & !(sapply(x, inherits, what="Date") | - sapply(x, inherits, what="POSIXt")) + isNum <- isNum & !(dapply(x, inherits, what="Date") | + dapply(x, inherits, what="POSIXt")) ## Which columns are factors --> convert them to character - isFac <- sapply(x, is.factor) - x[, isFac] <- lapply(x[, isFac, drop=FALSE], as.character) + isFac <- dapply(x, is.factor) + if(any(isFac)) + ## This conditional is necessary because if x is a matrix, even if + ## all(isFAC==FALSE), this assignment will coerce it to mode + ## character. This isn't a problem for dataframes. + x[, isFac] <- sapply(x[, isFac, drop=FALSE], as.character) ## Collect information about how format() will format columns. ## We need to get this info now, since format will turn all columns to character - tmp <- lapply(x, format.info, ...) + tmp <- dapply(x, format.info, ..., simplify=FALSE) + if(is.matrix(x)) tmp <- as.data.frame(tmp) tmp1 <- sapply(tmp, length) tmp <- t(as.data.frame(tmp)) retFormat$width <- tmp[, 1] - ## Collect other details for numeric columns if(any(isNum)) { ## Numeric columns with digits @@ -89,6 +115,9 @@ ## --- Format --- + ## store original object in 'y' + y <- x + ## Formatting (to character) for(i in 1:nCol) { if(widthNULL) { @@ -101,17 +130,17 @@ ## following test to "fiddle" with the value in 'na' argument since - ## NA should not increase the width of column with width 1, while wider ## value for 'na' should increase the width - test <- is.na(x[, i]) + test <- is.na(y[, i]) ## Make a copy to make sure we get character after first format() - Date class caused problems x2 <- character(length=nRow) ## Add formatted values - x2[!test] <- format(x[!test, i], justify=justify, width=tmp, ...) + x2[!test] <- format(y[!test, i], justify=justify, width=tmp, ...) ## Add 'na' value x2[test] <- na ## Replace the original x[, i] <- x2 ## Collect width (again) - tmp2 <- format.info(x[, i], ...)[1] + tmp2 <- format.info(x2, ...)[1] ## Reformat if 'na' value change the width of the column if(tmp2 != retFormat[i, "width"]) { retFormat[i, "width"] <- tmp2 @@ -128,7 +157,7 @@ ## Number of levels for "non-numeric"" columns if(any(!isNum)) { - retFormat[!isNum, "nlevels"] <- sapply(x[, !isNum, drop=FALSE], + retFormat[!isNum, "nlevels"] <- dapply(x[, !isNum, drop=FALSE], function(z) length(unique(z))) } @@ -158,7 +187,7 @@ na=na, row.names=FALSE, col.names=FALSE, - qmethod=qmethod) + qmethod=qmethod) } write.table(x=x, diff -Nru gdata-2.13.3/tests/test.humanReadable.R gdata-2.17.0/tests/test.humanReadable.R --- gdata-2.13.3/tests/test.humanReadable.R 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/tests/test.humanReadable.R 2015-04-25 16:40:38.000000000 +0000 @@ -0,0 +1,93 @@ +library(gdata) + +options(humanReadable=FALSE) + +set.seed(123456) + +baseSI <- 10 +powerSI <- seq(from=0, to=27, by=3) +SI0 <- (baseSI)^powerSI +k <- length(SI0) - 1 +SI1 <- SI0 - SI0 / c(2, runif(n=k, min=1.01, max=5.99)) +SI2 <- SI0 + SI0 / c(2, runif(n=k, min=1.01, max=5.99)) + +baseIEC <- 2 +powerIEC <- seq(from=0, to=90, by=10) +IEC0 <- (baseIEC)^powerIEC +IEC1 <- IEC0 - IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) +IEC2 <- IEC0 + IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) + +# Auto units, specify width +cbind(humanReadable(x=SI2, standard="SI", width=7), + humanReadable(x=SI2, standard="SI", width=5), + humanReadable(x=SI2, standard="SI", width=3), + humanReadable(x=IEC2, standard="IEC", width=7), + humanReadable(x=IEC2, standard="IEC", width=5), + humanReadable(x=IEC2, standard="IEC", width=3), + humanReadable(x=IEC2, standard="Unix", width=7), + humanReadable(x=IEC2, standard="Unix", width=5), + humanReadable(x=IEC2, standard="Unix", width=3)) + +# Auto units, specify digits +cbind(humanReadable(x=SI2, standard="SI", width=NULL, digits=7), + humanReadable(x=SI2, standard="SI", width=NULL, digits=3), + humanReadable(x=SI2, standard="SI", width=NULL, digits=2), + humanReadable(x=SI2, standard="SI", width=NULL, digits=1), + humanReadable(x=IEC2, standard="IEC", width=NULL, digits=7), + humanReadable(x=IEC2, standard="IEC", width=NULL, digits=3), + humanReadable(x=IEC2, standard="IEC", width=NULL, digits=2), + humanReadable(x=IEC2, standard="IEC", width=NULL, digits=1), + humanReadable(x=IEC2, standard="Unix", width=NULL, digits=7), + humanReadable(x=IEC2, standard="Unix", width=NULL, digits=3), + humanReadable(x=IEC2, standard="Unix", width=NULL, digits=2), + humanReadable(x=IEC2, standard="Unix", width=NULL, digits=1)) + +# Single unit, specify width +cbind(humanReadable(x=SI1, units="GB", standard="SI", width=7), + humanReadable(x=SI1, units="GB", standard="SI", width=5), + humanReadable(x=SI1, units="GB", standard="SI", width=3), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=7), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=5), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=3), + humanReadable(x=IEC1, units="G", standard="Unix", width=7), + humanReadable(x=IEC1, units="G", standard="Unix", width=5), + humanReadable(x=IEC1, units="G", standard="Unix", width=3) + ) + +# Single unit, specify digits +cbind(humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=7), + humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=3), + humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=2), + humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=1), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=7), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=3), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=2), + humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=1), + humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=7), + humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=3), + humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=2), + humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=1) + ) + + +stopifnot( is.object_sizes(as.object_sizes( 2^(1:30) ) ) ) +stopifnot( format(as.object_sizes(124)) == "124 bytes") +stopifnot( format(as.object_sizes(124e8), units="auto") == "11.5 GiB") +stopifnot( format(as.object_sizes(124e8), humanReadable=TRUE) == "11.5 GiB") +stopifnot( format(as.object_sizes(124e8), units="bytes") == "1.24e+10 bytes") + +tools::assertError( as.object_sizes(-1) ) +tools::assertError( as.object_sizes('a') ) +tools::assertError( as.object_sizes(list()) ) +tools::assertError( as.object_sizes(NULL) ) +tools::assertError( as.object_sizes(0+1i) ) + +stopifnot( format(as.object_sizes(1e40) ) == "1e+40 bytes" ) +stopifnot( format(as.object_sizes(1e40), units="auto" ) == "8.271806e+15 YiB") +stopifnot( format(as.object_sizes(1e40), units="bytes") == "1e+40 bytes" ) +stopifnot( format(as.object_sizes(1e40), humanReadable=TRUE) == "8.271806e+15 YiB") +stopifnot( format(as.object_sizes(1e40), humanReadable=FALSE) == "1e+40 bytes") + +options(humanReadable=TRUE) +stopifnot( format(as.object_sizes(1e40) ) == "8.271806e+15 YiB") +options(humanReadable=FALSE) diff -Nru gdata-2.13.3/tests/test.humanReadable.Rout.save gdata-2.17.0/tests/test.humanReadable.Rout.save --- gdata-2.13.3/tests/test.humanReadable.Rout.save 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/tests/test.humanReadable.Rout.save 2015-07-03 20:05:05.000000000 +0000 @@ -0,0 +1,238 @@ + +R version 3.2.0 (2015-04-16) -- "Full of Ingredients" +Copyright (C) 2015 The R Foundation for Statistical Computing +Platform: x86_64-apple-darwin13.4.0 (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under certain conditions. +Type 'license()' or 'licence()' for distribution details. + +R is a collaborative project with many contributors. +Type 'contributors()' for more information and +'citation()' on how to cite R or R packages in publications. + +Type 'demo()' for some demos, 'help()' for on-line help, or +'help.start()' for an HTML browser interface to help. +Type 'q()' to quit R. + +> library(gdata) +gdata: read.xls support for 'XLS' (Excel 97-2004) files ENABLED. + +gdata: read.xls support for 'XLSX' (Excel 2007+) files ENABLED. + +Attaching package: 'gdata' + +The following object is masked from 'package:stats': + + nobs + +The following object is masked from 'package:utils': + + object.size + +> +> options(humanReadable=FALSE) +> +> set.seed(123456) +> +> baseSI <- 10 +> powerSI <- seq(from=0, to=27, by=3) +> SI0 <- (baseSI)^powerSI +> k <- length(SI0) - 1 +> SI1 <- SI0 - SI0 / c(2, runif(n=k, min=1.01, max=5.99)) +> SI2 <- SI0 + SI0 / c(2, runif(n=k, min=1.01, max=5.99)) +> +> baseIEC <- 2 +> powerIEC <- seq(from=0, to=90, by=10) +> IEC0 <- (baseIEC)^powerIEC +> IEC1 <- IEC0 - IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) +> IEC2 <- IEC0 + IEC0 / c(2, runif(n=k, min=1.01, max=5.99)) +> +> # Auto units, specify width +> cbind(humanReadable(x=SI2, standard="SI", width=7), ++ humanReadable(x=SI2, standard="SI", width=5), ++ humanReadable(x=SI2, standard="SI", width=3), ++ humanReadable(x=IEC2, standard="IEC", width=7), ++ humanReadable(x=IEC2, standard="IEC", width=5), ++ humanReadable(x=IEC2, standard="IEC", width=3), ++ humanReadable(x=IEC2, standard="Unix", width=7), ++ humanReadable(x=IEC2, standard="Unix", width=5), ++ humanReadable(x=IEC2, standard="Unix", width=3)) + [,1] [,2] [,3] [,4] [,5] [,6] + [1,] " 2 B " " 2 B " " 2 B " " 2 B " " 2 B " " 2 B " + [2,] "1.54215 kB" "1.542 kB" " 1.5 kB" "1.18582 KiB" "1.186 KiB" " 1.2 KiB" + [3,] "1.20064 MB" "1.201 MB" " 1.2 MB" "1.19003 MiB" " 1.19 MiB" " 1.2 MiB" + [4,] "1.25207 GB" "1.252 GB" " 1.3 GB" "1.54448 GiB" "1.544 GiB" " 1.5 GiB" + [5,] "1.18121 TB" "1.181 TB" " 1.2 TB" "1.27667 TiB" "1.277 TiB" " 1.3 TiB" + [6,] " 1.1853 PB" "1.185 PB" " 1.2 PB" "1.18733 PiB" "1.187 PiB" " 1.2 PiB" + [7,] " 1.1678 EB" "1.168 EB" " 1.2 EB" "1.46271 EiB" "1.463 EiB" " 1.5 EiB" + [8,] "1.18275 ZB" "1.183 ZB" " 1.2 ZB" "1.62382 ZiB" "1.624 ZiB" " 1.6 ZiB" + [9,] "1.18568 YB" "1.186 YB" " 1.2 YB" "1.19557 YiB" "1.196 YiB" " 1.2 YiB" +[10,] "1501.49 YB" " 1501 YB" "1501 YB" "1750.35 YiB" " 1750 YiB" "1750 YiB" + [,7] [,8] [,9] + [1,] " 2 B" " 2 B" " 2 B" + [2,] "1.18582 K" "1.186 K" " 1.2 K" + [3,] "1.19003 M" " 1.19 M" " 1.2 M" + [4,] "1.54448 G" "1.544 G" " 1.5 G" + [5,] "1.27667 T" "1.277 T" " 1.3 T" + [6,] "1.18733 P" "1.187 P" " 1.2 P" + [7,] "1.46271 E" "1.463 E" " 1.5 E" + [8,] "1.62382 Z" "1.624 Z" " 1.6 Z" + [9,] "1.19557 Y" "1.196 Y" " 1.2 Y" +[10,] "1750.35 Y" " 1750 Y" "1750 Y" +> +> # Auto units, specify digits +> cbind(humanReadable(x=SI2, standard="SI", width=NULL, digits=7), ++ humanReadable(x=SI2, standard="SI", width=NULL, digits=3), ++ humanReadable(x=SI2, standard="SI", width=NULL, digits=2), ++ humanReadable(x=SI2, standard="SI", width=NULL, digits=1), ++ humanReadable(x=IEC2, standard="IEC", width=NULL, digits=7), ++ humanReadable(x=IEC2, standard="IEC", width=NULL, digits=3), ++ humanReadable(x=IEC2, standard="IEC", width=NULL, digits=2), ++ humanReadable(x=IEC2, standard="IEC", width=NULL, digits=1), ++ humanReadable(x=IEC2, standard="Unix", width=NULL, digits=7), ++ humanReadable(x=IEC2, standard="Unix", width=NULL, digits=3), ++ humanReadable(x=IEC2, standard="Unix", width=NULL, digits=2), ++ humanReadable(x=IEC2, standard="Unix", width=NULL, digits=1)) + [,1] [,2] [,3] [,4] + [1,] " 1.5000000 B " " 1.500 B " " 1.50 B " " 1.5 B " + [2,] " 1.5421535 kB" " 1.542 kB" " 1.54 kB" " 1.5 kB" + [3,] " 1.2006426 MB" " 1.201 MB" " 1.20 MB" " 1.2 MB" + [4,] " 1.2520737 GB" " 1.252 GB" " 1.25 GB" " 1.3 GB" + [5,] " 1.1812105 TB" " 1.181 TB" " 1.18 TB" " 1.2 TB" + [6,] " 1.1853010 PB" " 1.185 PB" " 1.19 PB" " 1.2 PB" + [7,] " 1.1678048 EB" " 1.168 EB" " 1.17 EB" " 1.2 EB" + [8,] " 1.1827531 ZB" " 1.183 ZB" " 1.18 ZB" " 1.2 ZB" + [9,] " 1.1856788 YB" " 1.186 YB" " 1.19 YB" " 1.2 YB" +[10,] "1501.4852409 YB" "1501.485 YB" "1501.49 YB" "1501.5 YB" + [,5] [,6] [,7] [,8] + [1,] " 1.5000000 B " " 1.500 B " " 1.50 B " " 1.5 B " + [2,] " 1.1858248 KiB" " 1.186 KiB" " 1.19 KiB" " 1.2 KiB" + [3,] " 1.1900302 MiB" " 1.190 MiB" " 1.19 MiB" " 1.2 MiB" + [4,] " 1.5444791 GiB" " 1.544 GiB" " 1.54 GiB" " 1.5 GiB" + [5,] " 1.2766723 TiB" " 1.277 TiB" " 1.28 TiB" " 1.3 TiB" + [6,] " 1.1873270 PiB" " 1.187 PiB" " 1.19 PiB" " 1.2 PiB" + [7,] " 1.4627144 EiB" " 1.463 EiB" " 1.46 EiB" " 1.5 EiB" + [8,] " 1.6238214 ZiB" " 1.624 ZiB" " 1.62 ZiB" " 1.6 ZiB" + [9,] " 1.1955693 YiB" " 1.196 YiB" " 1.20 YiB" " 1.2 YiB" +[10,] "1750.3547972 YiB" "1750.355 YiB" "1750.35 YiB" "1750.4 YiB" + [,9] [,10] [,11] [,12] + [1,] " 1.5000000 B" " 1.500 B" " 1.50 B" " 1.5 B" + [2,] " 1.1858248 K" " 1.186 K" " 1.19 K" " 1.2 K" + [3,] " 1.1900302 M" " 1.190 M" " 1.19 M" " 1.2 M" + [4,] " 1.5444791 G" " 1.544 G" " 1.54 G" " 1.5 G" + [5,] " 1.2766723 T" " 1.277 T" " 1.28 T" " 1.3 T" + [6,] " 1.1873270 P" " 1.187 P" " 1.19 P" " 1.2 P" + [7,] " 1.4627144 E" " 1.463 E" " 1.46 E" " 1.5 E" + [8,] " 1.6238214 Z" " 1.624 Z" " 1.62 Z" " 1.6 Z" + [9,] " 1.1955693 Y" " 1.196 Y" " 1.20 Y" " 1.2 Y" +[10,] "1750.3547972 Y" "1750.355 Y" "1750.35 Y" "1750.4 Y" +> +> # Single unit, specify width +> cbind(humanReadable(x=SI1, units="GB", standard="SI", width=7), ++ humanReadable(x=SI1, units="GB", standard="SI", width=5), ++ humanReadable(x=SI1, units="GB", standard="SI", width=3), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=7), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=5), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=3), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=7), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=5), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=3) ++ ) + [,1] [,2] [,3] [,4] [,5] [,6] + [1,] "5e-10 GB" "5e-10 GB" "5e-10 GB" "5e-10 GiB" "5e-10 GiB" "5e-10 GiB" + [2,] "8e-07 GB" "8e-07 GB" "8e-07 GB" "6e-07 GiB" "6e-07 GiB" "6e-07 GiB" + [3,] "8e-04 GB" "8e-04 GB" "8e-04 GB" "8e-04 GiB" "8e-04 GiB" "8e-04 GiB" + [4,] "7e-01 GB" "7e-01 GB" "7e-01 GB" "4e-01 GiB" "4e-01 GiB" "4e-01 GiB" + [5,] "6e+02 GB" "6e+02 GB" "6e+02 GB" "3e+02 GiB" "3e+02 GiB" "3e+02 GiB" + [6,] "6e+05 GB" "6e+05 GB" "6e+05 GB" "4e+05 GiB" "4e+05 GiB" "4e+05 GiB" + [7,] "5e+08 GB" "5e+08 GB" "5e+08 GB" "5e+08 GiB" "5e+08 GiB" "5e+08 GiB" + [8,] "7e+11 GB" "7e+11 GB" "7e+11 GB" "8e+11 GiB" "8e+11 GiB" "8e+11 GiB" + [9,] "3e+14 GB" "3e+14 GB" "3e+14 GB" "9e+14 GiB" "9e+14 GiB" "9e+14 GiB" +[10,] "8e+17 GB" "8e+17 GB" "8e+17 GB" "9e+17 GiB" "9e+17 GiB" "9e+17 GiB" + [,7] [,8] [,9] + [1,] "5e-10 G" "5e-10 G" "5e-10 G" + [2,] "6e-07 G" "6e-07 G" "6e-07 G" + [3,] "8e-04 G" "8e-04 G" "8e-04 G" + [4,] "4e-01 G" "4e-01 G" "4e-01 G" + [5,] "3e+02 G" "3e+02 G" "3e+02 G" + [6,] "4e+05 G" "4e+05 G" "4e+05 G" + [7,] "5e+08 G" "5e+08 G" "5e+08 G" + [8,] "8e+11 G" "8e+11 G" "8e+11 G" + [9,] "9e+14 G" "9e+14 G" "9e+14 G" +[10,] "9e+17 G" "9e+17 G" "9e+17 G" +> +> # Single unit, specify digits +> cbind(humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=7), ++ humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=3), ++ humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=2), ++ humanReadable(x=SI1, units="GB", standard="SI", width=NULL, digits=1), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=7), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=3), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=2), ++ humanReadable(x=IEC1, units="GiB", standard="IEC", width=NULL, digits=1), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=7), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=3), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=2), ++ humanReadable(x=IEC1, units="G", standard="Unix", width=NULL, digits=1) ++ ) + [,1] [,2] [,3] [,4] + [1,] "5.000000e-10 GB" "5.00e-10 GB" "5.0e-10 GB" "5e-10 GB" + [2,] "7.993163e-07 GB" "7.99e-07 GB" "8.0e-07 GB" "8e-07 GB" + [3,] "7.900375e-04 GB" "7.90e-04 GB" "7.9e-04 GB" "8e-04 GB" + [4,] "6.619855e-01 GB" "6.62e-01 GB" "6.6e-01 GB" "7e-01 GB" + [5,] "6.311259e+02 GB" "6.31e+02 GB" "6.3e+02 GB" "6e+02 GB" + [6,] "6.440324e+05 GB" "6.44e+05 GB" "6.4e+05 GB" "6e+05 GB" + [7,] "4.994386e+08 GB" "4.99e+08 GB" "5.0e+08 GB" "5e+08 GB" + [8,] "7.277869e+11 GB" "7.28e+11 GB" "7.3e+11 GB" "7e+11 GB" + [9,] "3.291745e+14 GB" "3.29e+14 GB" "3.3e+14 GB" "3e+14 GB" +[10,] "8.313511e+17 GB" "8.31e+17 GB" "8.3e+17 GB" "8e+17 GB" + [,5] [,6] [,7] [,8] + [1,] "4.656613e-10 GiB" "4.66e-10 GiB" "4.7e-10 GiB" "5e-10 GiB" + [2,] "5.975956e-07 GiB" "5.98e-07 GiB" "6.0e-07 GiB" "6e-07 GiB" + [3,] "7.764672e-04 GiB" "7.76e-04 GiB" "7.8e-04 GiB" "8e-04 GiB" + [4,] "4.459146e-01 GiB" "4.46e-01 GiB" "4.5e-01 GiB" "4e-01 GiB" + [5,] "2.985889e+02 GiB" "2.99e+02 GiB" "3.0e+02 GiB" "3e+02 GiB" + [6,] "4.209112e+05 GiB" "4.21e+05 GiB" "4.2e+05 GiB" "4e+05 GiB" + [7,] "4.983449e+08 GiB" "4.98e+08 GiB" "5.0e+08 GiB" "5e+08 GiB" + [8,] "7.751081e+11 GiB" "7.75e+11 GiB" "7.8e+11 GiB" "8e+11 GiB" + [9,] "8.756173e+14 GiB" "8.76e+14 GiB" "8.8e+14 GiB" "9e+14 GiB" +[10,] "9.390947e+17 GiB" "9.39e+17 GiB" "9.4e+17 GiB" "9e+17 GiB" + [,9] [,10] [,11] [,12] + [1,] "4.656613e-10 G" "4.66e-10 G" "4.7e-10 G" "5e-10 G" + [2,] "5.975956e-07 G" "5.98e-07 G" "6.0e-07 G" "6e-07 G" + [3,] "7.764672e-04 G" "7.76e-04 G" "7.8e-04 G" "8e-04 G" + [4,] "4.459146e-01 G" "4.46e-01 G" "4.5e-01 G" "4e-01 G" + [5,] "2.985889e+02 G" "2.99e+02 G" "3.0e+02 G" "3e+02 G" + [6,] "4.209112e+05 G" "4.21e+05 G" "4.2e+05 G" "4e+05 G" + [7,] "4.983449e+08 G" "4.98e+08 G" "5.0e+08 G" "5e+08 G" + [8,] "7.751081e+11 G" "7.75e+11 G" "7.8e+11 G" "8e+11 G" + [9,] "8.756173e+14 G" "8.76e+14 G" "8.8e+14 G" "9e+14 G" +[10,] "9.390947e+17 G" "9.39e+17 G" "9.4e+17 G" "9e+17 G" +> +> +> stopifnot( is.object_sizes(as.object_sizes( 2^(1:30) ) ) ) +> stopifnot( format(as.object_sizes(124)) == "124 bytes") +> stopifnot( format(as.object_sizes(124e8), units="auto") == "11.5 GiB") +> stopifnot( format(as.object_sizes(124e8), humanReadable=TRUE) == "11.5 GiB") +> stopifnot( format(as.object_sizes(124e8), units="bytes") == "1.24e+10 bytes") +> +> tools::assertError( as.object_sizes(-1) ) +> tools::assertError( as.object_sizes('a') ) +> tools::assertError( as.object_sizes(list()) ) +> tools::assertError( as.object_sizes(NULL) ) +> tools::assertError( as.object_sizes(0+1i) ) +> +> stopifnot( format(as.object_sizes(1e40) ) == "1e+40 bytes" ) +> stopifnot( format(as.object_sizes(1e40), units="auto" ) == "8.271806e+15 YiB") +> stopifnot( format(as.object_sizes(1e40), units="bytes") == "1e+40 bytes" ) +> stopifnot( format(as.object_sizes(1e40), humanReadable=TRUE) == "8.271806e+15 YiB") +> stopifnot( format(as.object_sizes(1e40), humanReadable=FALSE) == "1e+40 bytes") +> +> options(humanReadable=TRUE) +> stopifnot( format(as.object_sizes(1e40) ) == "8.271806e+15 YiB") +> options(humanReadable=FALSE) +> +> proc.time() + user system elapsed + 0.421 0.052 0.464 diff -Nru gdata-2.13.3/tests/test.read.xls.R gdata-2.17.0/tests/test.read.xls.R --- gdata-2.13.3/tests/test.read.xls.R 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/tests/test.read.xls.R 2015-07-03 20:04:21.000000000 +0000 @@ -23,19 +23,35 @@ exampleFile <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile.xls') -exampleFile2007 <- file.path(path.package('gdata'),'xls', +exampleFileX <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile.xlsx') # see the number and names of sheets: sheetCount(exampleFile) -if( 'XLSX' %in% xlsFormats() ) - sheetCount(exampleFile2007) +if(! 'XLSX' %in% xlsFormats() ) + { + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + sheetCount(exampleFileX) + } + sheetNames(exampleFile) -if( 'XLSX' %in% xlsFormats() ) - sheetNames(exampleFile2007) +if(! 'XLSX' %in% xlsFormats() ) + { + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + sheetNames(exampleFileX) + } + example.1 <- read.xls(exampleFile, sheet=1) # default is first worksheet example.1 @@ -46,54 +62,140 @@ example.3 <- read.xls(exampleFile, sheet=3, header=FALSE) # third worksheet by number example.3 -example.4 <- read.xls(exampleFile, sheet=3, header=FALSE) # third worksheet by number +example.4 <- read.xls(exampleFile, sheet=4, header=FALSE) # fourth worksheet by number example.4 -if( 'XLSX' %in% xlsFormats() ) +if(! 'XLSX' %in% xlsFormats() ) { - example.x.1 <- read.xls(exampleFile2007, sheet=1) # default is first worksheet - print(example.x.1) - - example.x.2 <- read.xls(exampleFile2007, sheet=2) # second worksheet by number - print(example.x.2) - - example.x.3 <- read.xls(exampleFile2007, sheet=3, header=FALSE) # third worksheet by number - print(example.x.3) - - example.x.4 <- read.xls(exampleFile2007, sheet=3, header=FALSE) # third worksheet by number - print(example.x.4) - - data <- read.xls(exampleFile2007, sheet="Sheet Second") # and by name - print(data) - - # load the third worksheet, skipping the first two non-data lines... - data <- read.xls(exampleFile2007, sheet="Sheet with initial text", skip=2) - print(data) -} - + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + example.x.1 <- read.xls(exampleFileX, sheet=1) # default is first worksheet + print(example.x.1) + + example.x.2 <- read.xls(exampleFileX, sheet=2) # second worksheet by number + print(example.x.2) + + example.x.3 <- read.xls(exampleFileX, sheet=3, header=FALSE) # third worksheet by number + print(example.x.3) + + example.x.4 <- read.xls(exampleFileX, sheet=4, header=FALSE) # fourth worksheet by number + print(example.x.4) + + data <- read.xls(exampleFileX, sheet="Sheet Second") # and by name + print(data) + + # load the third worksheet, skipping the first two non-data lines... + data <- read.xls(exampleFileX, sheet="Sheet with initial text", skip=2) + print(data) + } ## Check handling of skip.blank.lines=FALSE example.skip <- read.xls(exampleFile, sheet=2, blank.lines.skip=FALSE) example.skip -if( 'XLSX' %in% xlsFormats() ) +if(! 'XLSX' %in% xlsFormats() ) { - example.x.skip <- read.xls(exampleFile2007, sheet=2, blank.lines.skip=FALSE) + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + example.x.skip <- read.xls(exampleFileX, sheet=2, blank.lines.skip=FALSE) example.x.skip } + ## Check handing of fileEncoding for latin-1 characters -latin1File <- file.path(path.package('gdata'),'xls', 'latin-1.xls') +latin1File <- file.path(path.package('gdata'),'xls', 'latin-1.xls' ) latin1FileX <- file.path(path.package('gdata'),'xls', 'latin-1.xlsx') -example.latin1 <- read.xls(latin1File, fileEncoding='latin1') +if(.Platform$OS.type=="unix") + { + example.latin1 <- read.xls(latin1File, + fileEncoding='latin1', + encoding='latin1', + stringsAsFactors=FALSE) + } else { + example.latin1 <- read.xls(latin1File, + #fileEncoding='latin1', + encoding='latin1', + stringsAsFactors=FALSE) + } -if( 'XLSX' %in% xlsFormats() ) +if(! 'XLSX' %in% xlsFormats() ) { - example.latin1.x <- read.xls(latin1FileX, fileEncoding='latin1') + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + if(.Platform$OS.type=="unix") + { + example.latin1.x <- read.xls(latin1FileX, + fileEncoding='latin1', + encoding='latin1', + stringsAsFactors=FALSE) + } else { + example.latin1.x <- read.xls(latin1FileX, + #fileEncoding='latin1', + encoding='latin1', + stringsAsFactors=FALSE) + } } +## Check handling of very wide file + +wideFile <- file.path(path.package('gdata'),'xls', 'wide.xls' ) +wideFileX <- file.path(path.package('gdata'),'xls', 'wide.xlsx') + +example.wide <- read.xls(wideFile) +stopifnot(dim(example.wide)==c(0,256)) + +if( !'XLSX' %in% xlsFormats() ) + { + cat("************************************************************\n") + cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") + cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") + cat("************************************************************\n") + } else { + example.wide.x <- read.xls(wideFileX) + stopifnot(dim(example.wide.x)==c(0,16384)) + } + +## Check handling of files with dates calulcated relative to +## 1900-01-01 and 1904-01-01 + +file.1900 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1900.xls' ) +file.1904 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1904.xls' ) +fileX.1900 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1900.xlsx') +fileX.1904 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1904.xlsx') + +example.1900 <- read.xls(file.1900, sheet=3, header=FALSE) +example.1900 + +example.1904 <- read.xls(file.1904, sheet=3, header=FALSE) +example.1904 + +exampleX.1900 <- read.xls(file.1900, sheet=3, header=FALSE) +exampleX.1900 + +exampleX.1904 <- read.xls(file.1904, sheet=3, header=FALSE) +exampleX.1904 + +# all colmns should be identical +stopifnot( na.omit(example.1900 == exampleX.1900) ) +stopifnot( na.omit(example.1904 == exampleX.1904) ) + +# column 8 will differ by 1462 due to different date baselines (1900 vs 1904) +stopifnot( na.omit(example.1900 [,-8] == example.1904 [,-8]) ) +stopifnot( na.omit(exampleX.1900[,-8] == exampleX.1904[,-8]) ) + +stopifnot( na.omit(example.1900 [,8] - example.1904 [,8]) == 1462 ) +stopifnot( na.omit(exampleX.1900[,8] - exampleX.1904[,8]) == 1462 ) diff -Nru gdata-2.13.3/tests/test.read.xls.Rout.save gdata-2.17.0/tests/test.read.xls.Rout.save --- gdata-2.13.3/tests/test.read.xls.Rout.save 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/tests/test.read.xls.Rout.save 2015-07-03 20:05:20.000000000 +0000 @@ -1,7 +1,7 @@ -R version 3.0.1 (2013-05-16) -- "Good Sport" -Copyright (C) 2013 The R Foundation for Statistical Computing -Platform: i686-pc-linux-gnu (32-bit) +R version 3.2.0 (2015-04-16) -- "Full of Ingredients" +Copyright (C) 2015 The R Foundation for Statistical Computing +Platform: x86_64-apple-darwin13.4.0 (64-bit) R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under certain conditions. @@ -507,26 +507,42 @@ > exampleFile <- file.path(path.package('gdata'),'xls', + 'ExampleExcelFile.xls') > -> exampleFile2007 <- file.path(path.package('gdata'),'xls', +> exampleFileX <- file.path(path.package('gdata'),'xls', + 'ExampleExcelFile.xlsx') > > # see the number and names of sheets: > sheetCount(exampleFile) [1] 4 > -> if( 'XLSX' %in% xlsFormats() ) -+ sheetCount(exampleFile2007) +> if(! 'XLSX' %in% xlsFormats() ) ++ { ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ sheetCount(exampleFileX) ++ } [1] 4 > +> > sheetNames(exampleFile) [1] "Sheet First" "Sheet Second" [3] "Sheet with a very long name!" "Sheet with initial text" > -> if( 'XLSX' %in% xlsFormats() ) -+ sheetNames(exampleFile2007) +> if(! 'XLSX' %in% xlsFormats() ) ++ { ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ sheetNames(exampleFileX) ++ } [1] "Sheet First" "Sheet Second" [3] "Sheet with a very long name!" "Sheet with initial text" > +> > example.1 <- read.xls(exampleFile, sheet=1) # default is first worksheet > example.1 A B C @@ -548,53 +564,74 @@ > > example.3 <- read.xls(exampleFile, sheet=3, header=FALSE) # third worksheet by number > example.3 - V1 V2 V3 V4 V5 V6 -1 1 2001-01-01 1:01 0.2058182 NA A -2 2 2002-02-02 2:02 0.2910708 NA B -3 3 2003-03-03 3:03 0.3564875 -0.84147098 C -4 4 2004-04-04 4:04 0.4116363 0.70807342 -5 5 2005-05-05 5:05 0.4602234 0.50136797 A -6 6 2006-06-06 6:06 NA 0.25136984 B -7 7 2007-07-07 7:07 0.5445436 0.06318679 B -8 8 2008-08-08 8:08 0.5821416 NA C -9 9 2009-09-09 9:09 0.6174545 0.00000000 A -10 10 2010-10-10 10:10 0.6508541 0.00000000 A + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 36892.04 +2 37289.08 +3 37683.13 +4 38081.17 +5 38477.21 +6 38874.25 +7 39270.30 +8 39668.34 +9 40065.38 +10 40461.42 > -> example.4 <- read.xls(exampleFile, sheet=3, header=FALSE) # third worksheet by number +> example.4 <- read.xls(exampleFile, sheet=4, header=FALSE) # fourth worksheet by number > example.4 - V1 V2 V3 V4 V5 V6 -1 1 2001-01-01 1:01 0.2058182 NA A -2 2 2002-02-02 2:02 0.2910708 NA B -3 3 2003-03-03 3:03 0.3564875 -0.84147098 C -4 4 2004-04-04 4:04 0.4116363 0.70807342 -5 5 2005-05-05 5:05 0.4602234 0.50136797 A -6 6 2006-06-06 6:06 NA 0.25136984 B -7 7 2007-07-07 7:07 0.5445436 0.06318679 B -8 8 2008-08-08 8:08 0.5821416 NA C -9 9 2009-09-09 9:09 0.6174545 0.00000000 A -10 10 2010-10-10 10:10 0.6508541 0.00000000 A + V1 +1 This line contains text that would need to be skipped to get to the data +2 +3 +4 +5 +6 +7 + V2 V3 V4 V5 V6 V7 +1 +2 This line too! +3 D E F G Factor +4 FirstRow 1 <NA> <NA> <NA> Red +5 SecondRow 2 1 <NA> <NA> Green +6 ThirdRow 3 2 1 <NA> Red +7 FourthRow 4 3 2 1 Black > -> if( 'XLSX' %in% xlsFormats() ) +> if(! 'XLSX' %in% xlsFormats() ) + { -+ example.x.1 <- read.xls(exampleFile2007, sheet=1) # default is first worksheet -+ print(example.x.1) ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ example.x.1 <- read.xls(exampleFileX, sheet=1) # default is first worksheet ++ print(example.x.1) + -+ example.x.2 <- read.xls(exampleFile2007, sheet=2) # second worksheet by number -+ print(example.x.2) ++ example.x.2 <- read.xls(exampleFileX, sheet=2) # second worksheet by number ++ print(example.x.2) + -+ example.x.3 <- read.xls(exampleFile2007, sheet=3, header=FALSE) # third worksheet by number -+ print(example.x.3) ++ example.x.3 <- read.xls(exampleFileX, sheet=3, header=FALSE) # third worksheet by number ++ print(example.x.3) + -+ example.x.4 <- read.xls(exampleFile2007, sheet=3, header=FALSE) # third worksheet by number -+ print(example.x.4) ++ example.x.4 <- read.xls(exampleFileX, sheet=4, header=FALSE) # fourth worksheet by number ++ print(example.x.4) + -+ data <- read.xls(exampleFile2007, sheet="Sheet Second") # and by name -+ print(data) ++ data <- read.xls(exampleFileX, sheet="Sheet Second") # and by name ++ print(data) + -+ # load the third worksheet, skipping the first two non-data lines... -+ data <- read.xls(exampleFile2007, sheet="Sheet with initial text", skip=2) -+ print(data) -+ } ++ # load the third worksheet, skipping the first two non-data lines... ++ data <- read.xls(exampleFileX, sheet="Sheet with initial text", skip=2) ++ print(data) ++ } A B C 1 1 1 1 2 2 4 8 @@ -608,28 +645,44 @@ 2 SecondRow 2 1 NA NA Green 3 ThirdRow 3 2 1 NA Red 4 FourthRow 4 3 2 1 Black - V1 V2 V3 V4 V5 V6 -1 1 2001-01-01 1:01 0.2058182 NA A -2 2 2002-02-02 2:02 0.2910708 NA B -3 3 2003-03-03 3:03 0.3564875 -0.84147098 C -4 4 2004-04-04 4:04 0.4116363 0.70807342 -5 5 2005-05-05 5:05 0.4602234 0.50136797 A -6 6 2006-06-06 6:06 NA 0.25136984 B -7 7 2007-07-07 7:07 0.5445436 0.06318679 B -8 8 2008-08-08 8:08 0.5821416 NA C -9 9 2009-09-09 9:09 0.6174545 0.00000000 A -10 10 2010-10-10 10:10 0.6508541 0.00000000 A - V1 V2 V3 V4 V5 V6 -1 1 2001-01-01 1:01 0.2058182 NA A -2 2 2002-02-02 2:02 0.2910708 NA B -3 3 2003-03-03 3:03 0.3564875 -0.84147098 C -4 4 2004-04-04 4:04 0.4116363 0.70807342 -5 5 2005-05-05 5:05 0.4602234 0.50136797 A -6 6 2006-06-06 6:06 NA 0.25136984 B -7 7 2007-07-07 7:07 0.5445436 0.06318679 B -8 8 2008-08-08 8:08 0.5821416 NA C -9 9 2009-09-09 9:09 0.6174545 0.00000000 A -10 10 2010-10-10 10:10 0.6508541 0.00000000 A + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 36892.04 +2 37289.08 +3 37683.13 +4 38081.17 +5 38477.21 +6 38874.25 +7 39270.30 +8 39668.34 +9 40065.38 +10 40461.42 + V1 +1 This line contains text that would need to be skipped to get to the data +2 +3 +4 +5 +6 +7 + V2 V3 V4 V5 V6 V7 +1 +2 This line too! +3 D E F G Factor +4 FirstRow 1 <NA> <NA> <NA> Red +5 SecondRow 2 1 <NA> <NA> Green +6 ThirdRow 3 2 1 <NA> Red +7 FourthRow 4 3 2 1 Black X D E. F G Factor 1 FirstRow 1 NA NA NA Red 2 SecondRow 2 1 NA NA Green @@ -641,7 +694,6 @@ 3 NA ThirdRow 3 2 1 NA Red 4 NA FourthRow 4 3 2 1 Black > -> > ## Check handling of skip.blank.lines=FALSE > > example.skip <- read.xls(exampleFile, sheet=2, blank.lines.skip=FALSE) @@ -653,9 +705,14 @@ 4 ThirdRow 3 2 1 NA Red 5 FourthRow 4 3 2 1 Black > -> if( 'XLSX' %in% xlsFormats() ) +> if(! 'XLSX' %in% xlsFormats() ) + { -+ example.x.skip <- read.xls(exampleFile2007, sheet=2, blank.lines.skip=FALSE) ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ example.x.skip <- read.xls(exampleFileX, sheet=2, blank.lines.skip=FALSE) + example.x.skip + } X D E. F G Factor @@ -666,20 +723,185 @@ 5 FourthRow 4 3 2 1 Black > > +> > ## Check handing of fileEncoding for latin-1 characters > -> latin1File <- file.path(path.package('gdata'),'xls', 'latin-1.xls') +> latin1File <- file.path(path.package('gdata'),'xls', 'latin-1.xls' ) > latin1FileX <- file.path(path.package('gdata'),'xls', 'latin-1.xlsx') > -> example.latin1 <- read.xls(latin1File, fileEncoding='latin1') +> if(.Platform$OS.type=="unix") ++ { ++ example.latin1 <- read.xls(latin1File, ++ fileEncoding='latin1', ++ encoding='latin1', ++ stringsAsFactors=FALSE) ++ } else { ++ example.latin1 <- read.xls(latin1File, ++ #fileEncoding='latin1', ++ encoding='latin1', ++ stringsAsFactors=FALSE) ++ } > -> if( 'XLSX' %in% xlsFormats() ) +> if(! 'XLSX' %in% xlsFormats() ) + { -+ example.latin1.x <- read.xls(latin1FileX, fileEncoding='latin1') ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ if(.Platform$OS.type=="unix") ++ { ++ example.latin1.x <- read.xls(latin1FileX, ++ fileEncoding='latin1', ++ encoding='latin1', ++ stringsAsFactors=FALSE) ++ } else { ++ example.latin1.x <- read.xls(latin1FileX, ++ #fileEncoding='latin1', ++ encoding='latin1', ++ stringsAsFactors=FALSE) ++ } + } > > +> ## Check handling of very wide file +> +> wideFile <- file.path(path.package('gdata'),'xls', 'wide.xls' ) +> wideFileX <- file.path(path.package('gdata'),'xls', 'wide.xlsx') +> +> example.wide <- read.xls(wideFile) +> stopifnot(dim(example.wide)==c(0,256)) +> +> if( !'XLSX' %in% xlsFormats() ) ++ { ++ cat("************************************************************\n") ++ cat("** DIFF IN THIS SECTION IS EXPECTED BECAUSE PERL PACKAGES **\n") ++ cat("** FOR SUPPORTING XLSX ARE NOT INSTALLED **\n") ++ cat("************************************************************\n") ++ } else { ++ example.wide.x <- read.xls(wideFileX) ++ stopifnot(dim(example.wide.x)==c(0,16384)) ++ } +> +> ## Check handling of files with dates calulcated relative to +> ## 1900-01-01 and 1904-01-01 +> +> file.1900 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1900.xls' ) +> file.1904 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1904.xls' ) +> fileX.1900 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1900.xlsx') +> fileX.1904 <- file.path(path.package('gdata'),'xls', 'ExampleExcelFile_1904.xlsx') +> +> example.1900 <- read.xls(file.1900, sheet=3, header=FALSE) +> example.1900 + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 36892.04 +2 37289.08 +3 37683.13 +4 38081.17 +5 38477.21 +6 38874.25 +7 39270.30 +8 39668.34 +9 40065.38 +10 40461.42 +> +> example.1904 <- read.xls(file.1904, sheet=3, header=FALSE) +> example.1904 + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 35430.04 +2 35827.08 +3 36221.13 +4 36619.17 +5 37015.21 +6 37412.25 +7 37808.30 +8 38206.34 +9 38603.38 +10 38999.42 +> +> exampleX.1900 <- read.xls(file.1900, sheet=3, header=FALSE) +> exampleX.1900 + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 36892.04 +2 37289.08 +3 37683.13 +4 38081.17 +5 38477.21 +6 38874.25 +7 39270.30 +8 39668.34 +9 40065.38 +10 40461.42 +> +> exampleX.1904 <- read.xls(file.1904, sheet=3, header=FALSE) +> exampleX.1904 + V1 V2 V3 V4 V5 V6 V7 +1 1 2001-01-01 01:01:00.00 0.2058182 NA A 2001-01-01 01:01:01.01 +2 2 2002-02-02 02:02:00.00 0.2910708 NA B 2002-02-02 02:02:02.02 +3 3 2003-03-03 03:03:00.00 0.3564875 -0.84147098 C 2003-03-03 03:03:03.03 +4 4 2004-04-04 04:04:00.00 0.4116363 0.70807342 2004-04-04 04:04:04.04 +5 5 2005-05-05 05:05:00.00 0.4602234 0.50136797 A 2005-05-05 05:05:05.05 +6 6 2006-06-06 06:06:00.00 NA 0.25136984 B 2006-06-06 06:06:06.06 +7 7 2007-07-07 07:07:00.00 0.5445436 0.06318679 B 2007-07-07 07:07:07.07 +8 8 2008-08-08 08:08:00.00 0.5821416 NA C 2008-08-08 08:08:08.08 +9 9 2009-09-09 09:09:00.00 0.6174545 0.00000000 A 2009-09-09 09:09:09.09 +10 10 2010-10-10 10:10:00.00 0.6508541 0.00000000 A 2010-10-10 10:10:10.10 + V8 +1 35430.04 +2 35827.08 +3 36221.13 +4 36619.17 +5 37015.21 +6 37412.25 +7 37808.30 +8 38206.34 +9 38603.38 +10 38999.42 +> +> # all colmns should be identical +> stopifnot( na.omit(example.1900 == exampleX.1900) ) +> stopifnot( na.omit(example.1904 == exampleX.1904) ) +> +> # column 8 will differ by 1462 due to different date baselines (1900 vs 1904) +> stopifnot( na.omit(example.1900 [,-8] == example.1904 [,-8]) ) +> stopifnot( na.omit(exampleX.1900[,-8] == exampleX.1904[,-8]) ) +> +> stopifnot( na.omit(example.1900 [,8] - example.1904 [,8]) == 1462 ) +> stopifnot( na.omit(exampleX.1900[,8] - exampleX.1904[,8]) == 1462 ) > > proc.time() user system elapsed - 10.072 1.468 12.094 + 13.495 0.834 14.549 diff -Nru gdata-2.13.3/tests/test.reorder.factor.R gdata-2.17.0/tests/test.reorder.factor.R --- gdata-2.13.3/tests/test.reorder.factor.R 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/tests/test.reorder.factor.R 2015-04-23 02:37:51.000000000 +0000 @@ -0,0 +1,11 @@ +## Test results before and after loading gdata + +m <- factor(c('a','b','c')) + +( m1 <- reorder(m, X=c(3, 2, 1)) ) + +library(gdata) + +( m2 <- reorder(m, X=c(3, 2, 1)) ) + +stopifnot(identical(m1,m2)) diff -Nru gdata-2.13.3/tests/test.reorder.factor.Rout.save gdata-2.17.0/tests/test.reorder.factor.Rout.save --- gdata-2.13.3/tests/test.reorder.factor.Rout.save 1970-01-01 00:00:00.000000000 +0000 +++ gdata-2.17.0/tests/test.reorder.factor.Rout.save 2015-07-03 20:05:20.000000000 +0000 @@ -0,0 +1,56 @@ + +R version 3.2.0 (2015-04-16) -- "Full of Ingredients" +Copyright (C) 2015 The R Foundation for Statistical Computing +Platform: x86_64-apple-darwin13.4.0 (64-bit) + +R is free software and comes with ABSOLUTELY NO WARRANTY. +You are welcome to redistribute it under certain conditions. +Type 'license()' or 'licence()' for distribution details. + +R is a collaborative project with many contributors. +Type 'contributors()' for more information and +'citation()' on how to cite R or R packages in publications. + +Type 'demo()' for some demos, 'help()' for on-line help, or +'help.start()' for an HTML browser interface to help. +Type 'q()' to quit R. + +> ## Test results before and after loading gdata +> +> m <- factor(c('a','b','c')) +> +> ( m1 <- reorder(m, X=c(3, 2, 1)) ) +[1] a b c +attr(,"scores") +a b c +3 2 1 +Levels: c b a +> +> library(gdata) +gdata: read.xls support for 'XLS' (Excel 97-2004) files ENABLED. + +gdata: read.xls support for 'XLSX' (Excel 2007+) files ENABLED. + +Attaching package: 'gdata' + +The following object is masked from 'package:stats': + + nobs + +The following object is masked from 'package:utils': + + object.size + +> +> ( m2 <- reorder(m, X=c(3, 2, 1)) ) +[1] a b c +attr(,"scores") +a b c +3 2 1 +Levels: c b a +> +> stopifnot(identical(m1,m2)) +> +> proc.time() + user system elapsed + 0.341 0.046 0.381 diff -Nru gdata-2.13.3/tests/tests.write.fwf.Rout.save gdata-2.17.0/tests/tests.write.fwf.Rout.save --- gdata-2.13.3/tests/tests.write.fwf.Rout.save 2014-01-03 19:32:42.000000000 +0000 +++ gdata-2.17.0/tests/tests.write.fwf.Rout.save 2015-07-03 20:05:21.000000000 +0000 @@ -1,7 +1,7 @@ -R version 3.0.1 (2013-05-16) -- "Good Sport" -Copyright (C) 2013 The R Foundation for Statistical Computing -Platform: i686-pc-linux-gnu (32-bit) +R version 3.2.0 (2015-04-16) -- "Full of Ingredients" +Copyright (C) 2015 The R Foundation for Statistical Computing +Platform: x86_64-apple-darwin13.4.0 (64-bit) R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under certain conditions. @@ -231,4 +231,4 @@ > > proc.time() user system elapsed - 1.464 0.152 1.631 + 0.426 0.048 0.462 diff -Nru gdata-2.13.3/tests/unitTests/runit.write.fwf.R gdata-2.17.0/tests/unitTests/runit.write.fwf.R --- gdata-2.13.3/tests/unitTests/runit.write.fwf.R 2014-04-05 02:23:56.000000000 +0000 +++ gdata-2.17.0/tests/unitTests/runit.write.fwf.R 2015-04-25 16:23:33.000000000 +0000 @@ -1,7 +1,7 @@ ### runit.write.fwf.R ###------------------------------------------------------------------------ ### What: Unit tests for write.fwf -### $Id: runit.write.fwf.R 1784 2014-04-05 02:23:45Z warnes $ +### $Id: runit.write.fwf.R 1966 2015-04-25 16:23:31Z warnes $ ### Time-stamp: <2008-08-05 11:58:50 ggorjan> ###------------------------------------------------------------------------ @@ -59,9 +59,17 @@ digits=c(0, 1), exp=c(0, 0), stringsAsFactors=FALSE) - formatInfo <- write.fwf(testData[, c("num1", "num2")], formatInfo=TRUE) + + testData1 <- testData[, c("num1", "num2")] + testData1M <- as.matrix(testData1) + + formatInfo <- write.fwf(testData1, formatInfo=TRUE) checkEquals(formatInfo, formatInfoT) + formatInfoM <- write.fwf(testData1M, formatInfo=TRUE) + checkEquals(formatInfoM, formatInfoT) + + ## scientific notation dd <- options("digits"); options(digits = 7) testData2 <- data.frame(a=123, b=pi, c=1e8, d=1e222) @@ -91,39 +99,66 @@ digits=c(0, 0, 1), exp=c(0, 0, 0), stringsAsFactors=FALSE) - formatInfoR <- write.fwf(testData[, c("num1", "num2")], formatInfo=TRUE, - rownames=TRUE, rowCol="row") + testData3 <- testData[, c("num1", "num2")] + testData3M <- as.matrix(testData3) + + formatInfoR <- write.fwf(testData3, formatInfo=TRUE, rownames=TRUE, + rowCol="row") checkEquals(formatInfoR, formatInfoTR) + formatInfoR <- write.fwf(testData3M, formatInfo=TRUE, rownames=TRUE, + rowCol="row") + checkEquals(formatInfoR, formatInfoTR) + + ## quoteInfo alone does not have any effect - formatInfoI <- write.fwf(testData[, c("num1", "num2")], formatInfo=TRUE, - quoteInfo=TRUE) + formatInfoI <- write.fwf(testData3, formatInfo=TRUE, quoteInfo=TRUE) + checkEquals(formatInfoI, formatInfoT) + + formatInfoI <- write.fwf(testData3M, formatInfo=TRUE, quoteInfo=TRUE) checkEquals(formatInfoI, formatInfoT) ## quote - formatInfoQ <- write.fwf(testData[, c("num1", "num2")], formatInfo=TRUE, - quote=TRUE) formatInfoTQ <- formatInfoT formatInfoTQ$position <- c(1, 6) formatInfoTQ$width <- c(4, 5) + + formatInfoQ <- write.fwf(testData3, formatInfo=TRUE, quote=TRUE) + checkEquals(formatInfoQ, formatInfoTQ) + + formatInfoQ <- write.fwf(testData3M, formatInfo=TRUE, quote=TRUE) checkEquals(formatInfoQ, formatInfoTQ) ## quote without quoteInfo - formatInfoQI <- write.fwf(testData[, c("num1", "num2")], formatInfo=TRUE, - quote=TRUE, quoteInfo=FALSE) formatInfoTQI <- formatInfoT formatInfoTQI$position <- c(2, 6) + + formatInfoQI <- write.fwf(testData3, formatInfo=TRUE, quote=TRUE, + quoteInfo=FALSE) + checkEquals(formatInfoQI, formatInfoTQI) + + formatInfoQI <- write.fwf(testData3M, formatInfo=TRUE, quote=TRUE, + quoteInfo=FALSE) checkEquals(formatInfoQI, formatInfoTQI) ## width ## --> default width for num1 is 2 - formatInfo <- write.fwf(testData[, "num1", drop=FALSE], width=10, formatInfo=TRUE) + testData4 <- testData[, "num1", drop=FALSE] + testData4M <- as.matrix(testData[, "num1", drop=FALSE]) + + formatInfo <- write.fwf(testData4, width=10, formatInfo=TRUE) + checkEquals(formatInfo$width, 10) + + formatInfo <- write.fwf(testData4M, width=10, formatInfo=TRUE) checkEquals(formatInfo$width, 10) ## too small value in width (this also tests recycling) ## --> proper width for num1 is 2, while for num2 it is 3 checkException(write.fwf(testData[, c("num1", "num2")], width=2)) checkException(write.fwf(testData[, c("num1", "num2")], width=c(2, 1))) + + ## Done + cat("\nDONE.\n\n") } ### }}}