5

I'm making a jquery clone for C#. Right now I've got it set up so that every method is an extension method on IEnumerable<HtmlNode> so it works well with existing projects that are already using HtmlAgilityPack. I thought I could get away without preserving state... however, then I noticed jQuery has two methods .andSelf and .end which "pop" the most recently matched elements off an internal stack. I can mimic this functionality if I change my class so that it always operates on SharpQuery objects instead of enumerables, but there's still a problem.

With JavaScript, you're given the Html document automatically, but when working in C# you have to explicitly load it, and you could use more than one document if you wanted. It appears that when you call $('xxx') you're essentially creating a new jQuery object and starting fresh with an empty stack. In C#, you wouldn't want to do that, because you don't want to reload/refetch the document from the web. So instead, you load it once either into a SharpQuery object, or into an list of HtmlNodes (you just need the DocumentNode to get started).

In the jQuery docs, they give this example

$('ul.first').find('.foo')
  .css('background-color', 'red')
.end().find('.bar')
  .css('background-color', 'green')
.end();

I don't have an initializer method because I can't overload the () operator, so you just start with sq.Find() instead, which operates on the root of the document, essentially doing the same thing. But then people are going to try and write sq.Find() on one line, and then sq.Find() somewhere down the road, and (rightfully) expect it to operate on the root of the document again... but if I'm maintaining state, then you've just modified the context after the first call.

So... how should I design my API? Do I add another Init method that all queries should begin with that resets the stack (but then how do I force them to start with that?), or add a Reset() that they have to call at the end of their line? Do I overload the [] instead and tell them to start with that? Do I say "forget it, no one uses those state-preserved functions anyway?"

Basically, how would you like that jQuery example to be written in C#?

  1. sq["ul.first"].Find(".foo") ...
    Downfalls: Abuses the [] property.

  2. sq.Init("ul.first").Find(".foo") ...
    Downfalls: Nothing really forces the programmer to start with Init, unless I add some weird "initialized" mechanism; user might try starting with .Find and not get the result he was expecting. Also, Init and Find are pretty much identical anyway, except the former resets the stack too.

  3. sq.Find("ul.first").Find(".foo") ... .ClearStack()
    Downfalls: programmer may forget to clear the stack.

  4. Can't do it.
    end() not implemented.

  5. Use two different objects.
    Perhaps use HtmlDocument as the base that all queries should begin with, and then every method thereafter returns a SharpQuery object that can be chained. That way the HtmlDocument always maintains the initial state, but the SharpQuery objects may have different states. This unfortunately means I have to implement a bunch of stuff twice (once for HtmlDocument, once for the SharpQuery object).

  6. new SharpQuery(sq).Find("ul.first").Find(".foo") ...
    The constructor copies a reference to the document, but resets the stack.

mpen
  • 272,448
  • 266
  • 850
  • 1,236
  • 2
    IMO 5) is the best option. It's certainly readable and intuitive for the queries to begin from `HtmlDocument`, and as for the duplicate work -- hopefully you can implement it so that only the method signatures are duplicated, but not the actual logic. (Chaining the calls to some common class that does the work.) I also like option 1) and personally don't see it as an "abuse" of the brackets. :) – Kirk Woll Nov 04 '10 at 00:34
  • @Kirk: `[]` generally indicates an `O(1)` operation... like the data is already indexed. In this case, it actually has to do a full search. – mpen Nov 04 '10 at 00:43
  • Nevertheless, I'm leaning towards (1) now. Actually, I've started coding it this way. This prevents users from jumping right in with `.Find()` because the context isn't set until they call `[]`. i.e., `.Find()` simply won't find anything because it has nothing to search. `[]` resets the context to the document node and then they can begin searching. – mpen Nov 04 '10 at 04:09

2 Answers2

4

I think the major stumbling block you're running into here is that you're trying to get away with just having one SharpQuery object for each document. That's not how jQuery works; in general, jQuery objects are immutable. When you call a method that changes the set of elements (like find or end or add), it doesn't alter the existing object, but returns a new one:

var theBody = $('body');
// $('body')[0] is the <body>
theBody.find('div').text('This is a div');
// $('body')[0] is still the <body>

(see the documentation of end for more info)

SharpQuery should operate the same way. Once you create a SharpQuery object with a document, method calls should return new SharpQuery objects, referencing a different set of elements of the same document. For instance:

var sq = SharpQuery.Load(new Uri("http://api.jquery.com/category/selectors/"));
var header = sq.Find("h1"); // doesn't change sq
var allTheLinks = sq.Find(".title-link") // all .title-link in the whole document; also doesn't change sq
var someOfTheLinks = header.Find(".title-link"); // just the .title-link in the <h1>; again, doesn't change sq or header

The benefits of this approach are several. Because sq, header, allTheLinks, etc. are all the same class, you only have one implementation of each method. Yet each of these objects references the same document, so you don't have multiple copies of each node, and changes to the nodes are reflected in every SharpQuery object on that document (e.g. after allTheLinks.text("foo"), someOfTheLinks.text() == "foo".).

Implementing end and the other stack-based manipulations also becomes easy. As each method creates a new, filtered SharpQuery object from another, it retains a reference to that parent object (allTheLinks to header, header to sq). Then end is as simple as returning a new SharpQuery containing the same elements as the parent, like:

public SharpQuery end()
{
    return new SharpQuery(this.parent.GetAllElements());
}

(or however your syntax shakes out.)

I think this approach will get you the most jQuery-like behavior, with a fairly easy implementation. I'll definitely be keeping an eye on this project; it's a great idea.

kevingessner
  • 18,559
  • 5
  • 43
  • 63
  • Ahh..clever! I was thinking about returning a new object, but then I couldn't figure out how I would maintain the stack. Keeping a reference to the parent... so simple >. – mpen Nov 07 '10 at 19:50
  • Big update: http://sharp-query.googlecode.com/svn/trunk/HtmlAgilityPlus/ Uses this method for chaining now. – mpen Nov 14 '10 at 23:02
0

I would lean towards a variant on option 2. In jQuery $() is a function call. C# doesn't have global functions, a static function call is the closest. I would use a method that indicates you're creating a wrapper like..

SharpQuery.Create("ul.first").Find(".foo")

I wouldn't be concerned about shortening SharpQuery to sq since intellisense means users won't have to type the whole thing (and if they have resharper they only need to type SQ anyways).

Samuel Neff
  • 73,278
  • 17
  • 138
  • 182
  • They can name it whatever they want.. `sq` would be an instance of `SharpQuery`. `SharpQuery.Create` won't work as a static method because you have to load the document first... unless you want to make the document static too, but then you can only work with one document at a time; an arbitrary restriction. – mpen Nov 07 '10 at 17:11