What is the point of add_rewrite_rule()?

In theory, the add_rewrite_rule() function in rewrite.php is a good one. It provides a straightforward API for adding a simple rewrite rule and abstracts away the complexity of the $WP_Rewrite class.

In theory, one would expect to use it as follows:


function add_a_rule() {
add_rewrite_rule('/foobar/?$', "index.php?somvar=foobar", "top");
}
add_action('generate_rewrite_rules', 'add_a_rule');


And yet, the above code does not work, because add_rewrite_rule() adds the rules some place that does not ultimately get processed by the time the generate_rewrite_rules action is called.

So my question is, what is the purpose of the add_rewrite_rule() abstraction? It can be made to work by calling $wp_rewrite->flush_rules() following it, but there is no practical instance in which this is useful.

Note this is not a support request, I can add rules easily in any number of ways. This is more of a specific question about this function, and I guess an implicit statement that the $WP_Rewrite object is woefully lacking in decent abstractions. Even the example codes given in the “Using Permalinks” section seems to function by monkeying around with internals and skipping the abstractions.

Perhaps there is just some way this function is intended to be used that I have simply overlooked…if so I’d love to hear it.