What's the BNF of doctrine for?

It looks like a big mess,how does it work as reference?

http://www.doctrine-project.org/documentation/manual/1_1/en/dql-doctrine-query-language%3Abnf

Solution

I don't think it's used as a reference by any human-being, actually ; but it might be useful if someone want to use some automatic tool that understands BNF ; for instance, some kind of code generator.

The advantage of BNF being that's it's a formal way to describe a language -- much more easier to understand than english, when you are a program.

For reference :

Edit after the comments : Here's a quick example about the DQL / Object stuff :

Let's consider this portion of code, which is using the object-oriented API to write a query, execute it, and get the results (hydrated as arrays -- prints out only the data, this way, when debugging) :

$result = Doctrine_Query::create()
    ->select('p.id, p.title, u.login')
            ->from('Ab_Model_Post p')
            ->innerJoin('p.User u')
            ->where('p.codeStatus = ?')
            ->orderBy('p.date desc')
            ->limit(2)
            ->execute(array('OK'), Doctrine::HYDRATE_ARRAY);
var_dump($result);

And here's the kind of output you'll get :

array
  0 => 
    array
      'id' => string '7' (length=1)
      'title' => string 'Septième post' (length=14)
      'User' => 
        array
          'id' => string '1' (length=1)
          'login' => string 'user1' (length=5)
  1 => 
    array
      'id' => string '6' (length=1)
      'title' => string 'Sixième post (draft=7)' (length=23)
      'User' => 
        array
          'id' => string '1' (length=1)
          'login' => string 'user1' (length=5)

Of course, this is considering the schema and models classes are OK -- and sorry for the example in french, I used a schema/model/database I set up some time ago for a demonstration of Doctrine, which was in french.

Basically, the DB is for a blogging application, and, here, we :

get some data from posts and the user who posted them
for valid posts
the most recents posts
only two posts

Now, here's an equivalent, using what I meant by "DQL" as in "pseudo-SQL language" :

$result = Doctrine_Query::create()
    ->query(<<<DQL
select p.id, p.title, u.login
from Ab_Model_Post as p, 
    p.User u
where p.codeStatus = ?
order by p.date desc
limit 2
DQL
    , array('OK'), Doctrine::HYDRATE_ARRAY);
var_dump($result);

No object-oriented API here (well, to write the query, I mean) : I only wrote that pseudo-SQL I was thinking about -- which is what the BNF describes, as far as I can tell.

And, of course, the output of the var_dump is exactly the same as the one I got before.

I hope this makes things a bit more clear :-)