2013-06-21

[GNOME] GXml's summer adventure: API bikeshedding to start!

If you are a developer interested in using GXml or interested in XML in GNOME, I'd appreciate your feedback on two proposed API changes contained below. :)

 

So GXml is back in the Google Summer of Code under the mentorship of Owen Taylor, and it's my pleasure to be able to focus time on it again, before I finally graduate.  Over the next week, I'm going to write 6 articles about the key focuses for this summer


  • Developer support: API changes

  • Developer support: migration guide, examples, patches

  • Developer support: library documentation, usage examples, online and devhelp

  • Measurements: Memory

  • Measurements: CPU, scalability

  • Measurements: developer impact


Just so you know, work done so far includes


  • cleaning up the GXml Bugzilla by closing resolved bugs and responding to others.

  • plugged the most severe memory leaks, which is its own post, which will document how I did it! 

  • test ports of dconf and glade (still testing)



Developer support


Improving developer support is the main focus for this GSoC, and it includes these tasks:


  • clean up and break API (GError & GXmlDomNode: today's topic)

  • improve examples of usage

  • improve documentation for usage

  • make sure documentation is available online and in devhelp

  • push to get external patches accepted (e.g. libxml2's vapi changes)

  • more test ports, get patches accepted :D


Today I'm just going to talk about the first task.


Proposed API changes


With the idea of making development and code readability as frictionless as possible, there are two largely cosmetic but API-breaking changes I'm considering now, before 1.0. 

 

Proposal 1: GXmlDomNode: Rename to GXmlNode



The motivation for this is that


  • GXmlNode will result in less typing and make it easier to read

  • GXmlDomNode is inconsistent with other names, because it's the only one that specifies its part of the DOM (we don't do GXmlDomDocument) besides DomError (which mirrors DomException in the DOM Core spec).


It's named GXmlDomNode because, with namespaced languages, GXml.Node would conflict with GLib.Node (GNode), and at the time I didn't want to write GXml.Node all the time.  However, GXml.Node isn't much worse than writing DomNode in a namespaced language, and GXmlNode is much nicer than GXmlDomNode in C.  Especially when you start working on its methods, like gxml_dom_node_append_child ();



Thoughts?  Please provide feedback as a comment below or e-mail me directly!



Proposal 2: GError: remove parametre, use global-ish variable?



Some people previously complained about our explicit handling of errors through a GError parametre as cumbersome and inefficient.  Also, the way GXml has started using GError may be excessive and not how GError was intended to be used. 



[UPDATE: GError's documentation specifically rejects using GError for programming errors, since it's intended only for run-time errors.  I've written a post analysing DOMExceptions, and whether they qualify as run-time errors or programming errors.  Comments welcome, there, too.  I basically conclude that most of the DOMExceptions are programming errors and don't qualify for GError reporting.]



The DOM Core spec specifies many possible DOMExceptions to be raised.   Currently, the methods that are expected to raise an exception are declared to throw a GXml.DOMError, but in reality, many of those do not throw anything.  (I filed bug 702832 on vala requesting warnings for functions that declare errors that are never thrown.)  I haven't implemented error handling in most of the situations because they often seem truly exceptional, and are cases that the programmer should be able to anticipate and deal with in advance  [UPDATE: and thus, I feel, programming errors, and not appropriate for GError].  (I will pragmatically support DOMExceptions as needed in the future; file a bug if you want one supported!)



Consequently, I am considering breaking API and to cease throwing errors, instead switching to either setting a thread-specific global error variable, or a document-level error variable.  I'd document whether a method might set an error, so someone can check.   This is similar to what libxml2 already does, with its xmlGetLastError.  The document's return value would also provide some indication that something went wrong (e.g. NULL).



[UPDATE: additionally, we can allow verbose error reporting, so if a programming error is encountered, we'll use g_warning () or g_error () to log it with where it happened, and where in the document.]



Right now, the functions that do throw GErrors are mostly GXmlDocument constructors, GXmlDocument factory methods (it constructs any other GXml node type), and GXmlDomNode children management (insert, replace, etc), which are all very common.  In theory, if we're going to raise an exception for everything as requested by the DOM Core spec, though, there'd be many more, and we'd have to break API anyway to support it all.



The result of removing most GError reporting should be in general usage, code should be a little
smaller and easier to read, with less unnecessary text, while cases
where errors are anticipated can still be caught and checked.  [UPDATE: also, we'll comply with the intent of GError]



Please provide feedback as a comment below or e-mail me directly!  Also feel free to debate the nature of DOMExceptions.




Example of changes: C

For those who don't need errors:



GXmlDomNode *vader = gxml_document_create_element (doc, "DarthVader", NULL);

GXmlDomNode *luke = gxml_document_create_element (doc, "LukeSkywalker", NULL);

gxml_dom_node_append_child (vader, luke, NULL)



becomes:

GXmlNode *vader = gxml_document_create_element (doc, "DarthVader");

GXmlNode *luke = gxml_document_create_element (doc, "LukeSkywalker");

gxml_node_append_child (vader, luke);





For those who do need the errors:



GError *error = NULL;



GXmlDomNode *vader = gxml_document_create_element (doc, "DarthVader", &error);

if (error != NULL) {

  // handle error



GXmlDomNode *luke = gxml_document_create_element (doc, "LukeSkywalker", &error);

if (error != NULL) {

  // handle error


gxml_dom_node_append_child (vader, luke, &error)

if (error != NULL) {

  // handle error







becomes:  



GError *error = NULL;



GXmlNode *vader = gxml_document_create_element (doc, "DarthVader");

if ((error = gxml_last_error ()) != NULL) {

  // handle error



GXmlNode *luke = gxml_document_create_element (doc, "LukeSkywalker");

if ((error = gxml_last_error ()) != NULL) {

  // handle error



gxml_node_append_child (vader, luke)

if ((error = gxml_last_error ()) != NULL) {

  // handle error

}



Example of changes: Vala

For those who don't need errors:



try {

  DomNode darth = doc.create_element ("DarthVader");

  DomNode luke = doc.create_element ("LukeSkywalker");

  darth.append_child (luke);

} catch (DomError e) {

}



becomes:



GXml.Node darth = doc.create_element ("DarthVader");GXml.Node luke = doc.create_element ("LukeSkywalker");

darth.append_child (luke);



For those who do need errors:



try {

  DomNode darth = doc.create_element ("DarthVader");

  DomNode luke = doc.create_element ("LukeSkywalker");

  darth.append_child (luke);

} catch (DomError e) {

  // handle error

}



becomes:



GXml.Node darth = doc.create_element ("DarthVader");

if (GXml.last_error != null) {

  // handle error



GXml.Node luke = doc.create_element ("LukeSkywalker");

if (GXml.last_error != null) {

  // handle error



darth.append_child (luke);

if (GXml.last_error != null) {

  // handle error







I will appreciate any feedback. :)

Keine Kommentare:

Kommentar veröffentlichen

Dieses Blog durchsuchen

Labels

#Technology #GNOME gnome gxml fedora bugs linux vala google #General firefox security gsoc GUADEC android bug xml fedora 18 javascript libxml2 programming web blogger encryption fedora 17 gdom git emacs libgdata memory mozilla open source serialisation upgrade web development API Spain containers design evolution fedora 16 fedora 20 fedora 22 fedup file systems friends future glib gnome shell internet luks music performance phone photos php podman preupgrade tablet testing typescript yum #Microblog Network Manager adb apache art automation bash brno catastrophe css data loss debian debugging deja-dup disaster docker emusic errors ext4 facebook fedora 19 gee gir gitlab gitorious gmail gobject google talk google+ html libxml mail microsoft mtp mysql namespaces nautilus nextcloud owncloud picasaweb pitivi ptp python raspberry pi resizing rpm school selinux signal sms speech dispatcher systemd technology texting time management uoguelph usability video web design youtube #Tech Air Canada C Electron Element Empathy Europe GError GNOME 3 GNOME Files Go Google Play Music Grimes IRC Mac OS X Mario Kart Memento Nintendo Nintendo Switch PEAP Selenium Splatoon UI VPN Xiki accessibility advertising ai albums anaconda anonymity apple ask asus eee top automake autonomous automobiles b43 backup battery berlin bit rot broadcom browsers browsing canada canadian english cars chrome clarity comments communication compiler complaints computer computers configuration console constructive criticism cron cropping customisation dataloss dconf debug symbols design patterns desktop summit development discoverability distribution diy dnf documentation drm duplicity e-mail efficiency email english environment estate experimenting ext3 fedora 11 festival file formats firejail flac flatpak forgottotagit freedom friendship fuse galaxy nexus galton gay rights gdb german germany gimp gio gjs gnome software gnome-control-center google assistant google calendar google chrome google hangouts google reader gqe graphviz growth gtest gtg gtk gvfs gvfs metadata hard drive hard drives hardware help hp humour ide identity instagram installation instant messaging integration intel interactivity introspection jabber java java 13 jobs kernel keyboard language language servers languages law learning lenovo letsencrypt libreoffice librpm life livecd liveusb login lsp macbook maintainership mariadb mario matrix memory leaks messaging mounting mouse netflix new zealand node nodelist numix obama oci ogg oggenc oh the humanity open open standards openoffice optimisation org-mode organisation package management packagekit paint shedding parallelism pdo perl pipelight privacy productivity progress progressive web apps pumpkin pwa pyright quality recursion redhat refactoring repairs report rhythmbox sandboxes scheduling screenshots self-navigating car shell sleep smartphones software software engineering speed sql ssd synergy tabs test tests themes thesis tracker travel triumf turtles tv tweak twist typing university update usb user experience valadoc video editing volunteering vpnc waf warm wayland weather web apps website wifi wiki wireless wishes work xinput xmpp xorg xpath
Powered by Blogger.