Skip to content
Go to file
This branch is 1939 commits ahead of wakaba:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


=head1 NAME Web::DOM - A Perl DOM implementation =head1 SYNOPSIS use Web::DOM::Document; my $doc = new Web::DOM::Document; my $el = $doc->create_element ('a'); $el->set_attribute (href => ''); $doc->append_child ($el); =head1 DESCRIPTION The C modules is a pure-Perl DOM implementation. It implements various Web standard specifications, including DOM Living Standard and HTML Living Standard. =head1 USAGE The L module provides the C method returning a new document object, which corresponds to the C constructor in JavaScript Web browser environment. my $doc = new Web::DOM::Document; # XML document by default $doc->manakai_is_html (1); # Change to HTML document Using the document object, the application can create various DOM object, using standard DOM methods: my $el = $doc->create_element ('p'); # HTML element my $el = $doc->create_element_ns ($nsurl, $qname); $el->set_attribute (class => 'hoge fuga'); my $text = $doc->create_text_node ('text'); my $comment = $doc->create_comment ('data'); Please note that DOM attributes and methods are available in perllish_underscored_name rather than domSpecificationsCamelCaseName. Alternatively, you can instantiate the document object from an HTML or XML string, using the C interface: my $parser = new Web::DOM::Parser; my $doc = $parser->parse_from_string ($string, 'text/html'); my $doc = $parser->parse_from_string ($string, 'application/xhtml+xml'); Your favorite query methods are also available: $el = $doc->get_element_by_id ('site-logo'); $el = $doc->query_selector ('article > p:first-child'); $el = $doc->evaluate ('//div[child::p]', $doc)->iterate_next; $col = $doc->get_elements_by_tag_name ('p'); $col = $doc->get_elements_by_class_name ('blog-entry'); $col = $doc->images; For more information, see documentation of relevant modules. For example, methods available on the document object is listed in the L documentation. Frequently used modules include: =over 4 =item L The C interface. =item L The C interface. =item L The C interface. =item L The C interface. =item L The C interface. =back =head1 DOM MAPPING The modules implement the manakai's DOM Perl Binding specification , which defines the mapping between WebIDL/DOM and Perl. As a general rule, the object implementing the DOM interface I is an instance of the class (or the class that is a subclass of the class) C. However, applications should not rely on this, as the class inheritance hierarchy could be different from the interface's one, and could be changed in future revision of the module implementation. In particular, applications should not test whether the object is an instance of the interface that is defined with the C<[NoInterfaceObject]> extended attribute. For example, the C interface is defined with the extended attribute. The L class inherits the L class, as the C interface implements the C interface according to the DOM Standard, but applications should not test C<< $node->isa ('Web::DOM::ParentNode') >>. The constructor of a DOM interface, if any, is implemented as the C class method. For example, the constructor of the C interface can be invoked by C<< Web::DOM::Document->new >>. Attributes, methods, and constants of a DOM interface can be accessible as methods of the object implementing the interface. For example, the C attribute of the C interface is accessible as the C method of the element objects. If a method corresponding to the attribute is invoked with no argument, it acts as the getter of the attribute. If the method is invoked with an argument, it acts as the setter of the attribute. $string_returned_by_getter = $el->inner_html; $el->inner_html ($string_received_by_setter); $string_returned_by_method = $el->get_attribute ($string); $el->node_type == $el->ELEMENT_NODE; Some objects accept array operations: @children = @{$el->child_nodes}; $length = @{$el->child_nodes}; $first_child = $el->child_nodes->[0]; $second_child = $el->child_nodes->[1]; $second_last_child = $el->child_nodes->[-2]; =head1 CONSTRUCTORS Following classes have the constructor (i.e. the C method): =over 4 =item L =item L and its subclasses =item L =item L =item L =item L =back =head1 CONSTANTS Following modules export constants (by loading them using the C statement): =over 4 =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =back =head1 NOTE ON PRIVATE METHODS Some classes contain private methods and variables. Applications must not invoke or use them. As a general rule methods with name starting by C<_> is private, although there might be exceptions (e.g. C<_manakai_border_spacing_x> method, reflecting CSS C<-manakai-border-spacing-x> property, is not a private method). Anything EXCEPT for followings are private and should not be used: =over 4 =item DOM APIs as documented in relevant pod documentation For example, C, C, C, and C are explicitly mentioned in their pod section. =item Perl standard operations For example, C and C methods of any object, C<""> and C<0+> operation of any object, C<$Web::DOM::Document::VERSION> variable, C operation (which implicitly invokes the C method). Applications can also rely on C method with class name derived from DOM interface name whose definition does not contain C<[NoInterfaceObject]>. For example, C<< $object->isa ('Web::DOM::Node') >> does (and will) work as intended, while C<< $object->isa ('Web::DOM::CanvasPathMethod') >> (defined with C<[NoInterfaceObject]>) or C<< $object->isa ('Web::DOM::StringArray') >> (not derived from a DOM interface name) might not. However, it is not considered a good practice to compare objects by its class name in sophiscated object-oriented programs. =back Public APIs are not intended to be changed backward incompatibly in later stage of the development of these modules unless it is really necessary for some significant reasons (e.g. security concerns, or to resolve spec compatibility issues). Anything else could be changed, including package/file mapping of classes which do not provide constructors or constants. =head1 SPECIFICATIONS Specifications defining features supported by the modules include: =over =item DOM DOM Standard . =item DOMPARSING DOM Parsing and Serialization Standard . =item DOM3CORE Document Object Model (DOM) Level 3 Core Specification . =item DOMXPATH Document Object Model XPath . =item HTML HTML Standard . =item DOMDTDEF DOM Document Type Definitions . =item DOMPERL manakai's DOM Perl Binding . =item MANAKAI manakai DOM Extensions . =back For the complete list of relevant specifications, see documentations of the modules. =head1 DEPENDENCY The modules require Perl 5.10 or later. Following features require the perl-web-markup package (L and its family): C, C, C, C, and C; (L and related modules): C and C; (L: C). Following features require the perl-web-css package : C, C, C, C and its subclasses, and C. Following features require the perl-web-encodings package : setter of C method of C and C. Features performing URL-related operations require the perl-web-url package , which depends on the perl-web-encodings package . Such features include: C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, and C. Following features require modules in the perl-web-datetime package : C of L, C, C, C, and C. =head2 Using CSS, Selectors, and Media Queries How CSS style sheets are parsed and how CSSOM tree structure looks like depend on how much of CSS features are supported by the user agent. Since the web-dom module set by itself is not a rendering engine, most CSS features are considered as "not supported", therefore by default parsing discards most of CSS declarations. If you'd like to construct a CSS-based application on the top of the web-dom module set, you should turn on features you are supporting, through L module in the web-css package. The L object for a document's CSS parser can be accessed like this: use Web::CSS::Parser; my $parser = Web::CSS::Parser->get_parser_for_document ($doc); $resolver = $parser->media_resolver; ... where $doc is the document node with which the CSS style sheet in question will be associated. Then, you can set the "supported" flag of features you are supporting, like this: $resolver->{prop}->{display} = 1; $resolver->{prop_value}->{display}->{block} = 1; For more information on usage of the resolver, see L in the web-css package. =head1 DEVELOPMENT Latest version of the modules is available from the GitHub repository: . Test results can be reviewed at: . =head1 HISTORY The manakai project has been developed several generations of DOM implementation. The current DOM3 implementation had been worked since 2007. The C modules has been developed as replacement for those modules, supporting the current DOM Standard. It does not reuse most of the code of the older implementation, and many useless DOM3 features are not implemented. However, it does implement some DOM3 features that is really necessary for backward compatibility, as well as non-standard manakai extensions. It should be possible for applications using the old implementation to migrate to the new implementation by just replacing class name and as such. =head2 Obsolete features Following features fully or partially implemented in previous versions of manakai DOM implementations are considered obsolete and will not be implemented by these modules unless they are reintroduced by some DOM specification or found to be necessary for backward compatibility: DOMImplementationRegistry, DOMImplementationSource, DOMImplementationList, DOM features, DOMStringList, StringExtended, read-only nodes, EntityReference, CDATASection, replaceWholeText, isElementContentWhitespace, specified setter, hasReplacementTree setter, DOM3 configuration parameters, configuration parameters for DOM3 spec compatible DTD-based node operations, DOM3 DOMError, DOM Standard DOMError, DOMErrorHandler, UserDataHandler, DOMLocator, isId and family, internalSubset, TypeInfo and schemaTypeInfo, DOM3 LS, namespaces for DOM3 events, EventException, MutationEvent, MutationNameEvent, TextEvent, DocumentEvent->canDispatch, DocumentType->implementation, Document->createXHTMLDocument, URIReference, InternetMediaType, MANAKAI_FILTER_OPAQUE, Document->manakaiCreateSerialWalker, SerialWalker. HTMLElement->irrelevant, HTMLAnchorElement->media, HTMLAreaElement->media, HTMLCommandElement, HTMLDataGridElement, HTMLEventSourceElement, HTMLIsIndexElement, HTMLLegendElement->form, HTMLMenuElement->autosubmit, HTMLBlockquoteElement, HTMLStrictlyInlineContainerExtended, HTMLStructuredInlineContainerExtended, HTMLStructuredInlineContainerExtended, HTMLSectioningElementExtended, HTMLListElementExtended, HTMLDListElementExtended, CSSStyleDeclaration->styleFloat. Overloaded operators C<==>, C, and C<.=>, write operations through overloaded C<@{}> and C<%{}> operators for NodeList, NamedNodeMap, and HTMLCollection. Attr, Entity, and AttributeDefinition nodes can no longer contain Text nodes. By default the C node can no longer contain C nodes as children. The old behavior can be restored by setting a true value to the C configuration parameter (See L). The C attribute no longer disables random exceptions as defined in DOM3 specification; its scope is formally defined in the manakai DOM Extensions specification [MANAKAI]. =head1 TODO The initial milestone of the project is reimplementing the subset of DOM supported by the original manakai's DOM implementation , except for obsolete features. Following features will be (re)implemented in due course: =over 4 =item CSSOM Cascading API getComputedStyle [CSSOM], Element.prototype.manakaiComputedStyle, Window.prototype.manakaiGetComputedStyle, Window.prototype.setDocument [MANAKAI] =item WebVTT DOM [HTML] [WEBVTT] =back More features not supported by previous versions of manakai DOM implementation are expected to be implemented as well, including but not limited to: =over 4 =item HTMLFormControlsCollection, HTMLOptionsCollection [HTML] =item Mutation observers [DOM] =item Selectors API Level 2 features =item DocumentStyle API [CSSOM] =item API [CSSOM] =item @font-face, @page [CSSOM] =item SVGElement->style [CSSOM] =item GetStyleUtils, PseudoElement [CSSOM] =item New mutation methods [DOM] prepend, append, before, after, replace, remove =item DOM Ranges DOM Ranges interfaces and methods [DOM]; Ranges support in DOM Core methods and attributes [DOM]; Range.prototype.createContextualFragment [DOMPARSING]. =item Shadow DOM [DOM] =item Custom Elements [DOM, HTML] =back In addition, source codes of the modules include many "XXX" markers, indicating TODO items. Middle priority: URL; Encoding; Promise. Lower priority: Form API; HTMLMediaElement and related interfaces; Canvas; The ImageBitmap interface; The Screen interface; SVG; DnD; The RelatedEvent interface; The Window interface and related interfaces; The History interface and related interfaces; The Location interface; The Navigator interface and related interfaces; Scripting; Workers; Console; XHR; EventSource; WebSocket; postMessage and related interfaces; Storage; IndexedDB; Fullscreen; Notifications. JS-compatible C, C objects. Very low priority: Zip; XSLT 1.0. At the time of writing, there is no plan to implement the C attribute of the C interface (Instead, the C method is implemented). =head1 LIMITATIONS Methods returning the index or position in some list or string, whose IDL type is a number type, do not convert the value as specified by the WebIDL specification and the DOM Perl Binding specification. This should not be a problem as it is not realistic to have lists of items whose length is greater than, or nearly equal to 2**31 in both Perl's runtime environment and realworld use cases. Although the modules implement APIs as used in the Web platform, they does not support the Web's security model, i.e. the same-origin policy. It does not make sense for Perl applications. =head1 AUTHOR Wakaba . =head1 LICENSE Copyright 2007-2019 Wakaba . This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut


A pure-Perl DOM implementation



No releases published


You can’t perform that action at this time.