Allow drush command files to define functions that control whether or not they will be loaded

Here we have drush dispatching on steroids.

To illustrate what can be done with this patch, please consider the following brief walkthrough.

Step 1: Add some hook functions to your drushrc.php file:

function drush_magical_pre_sql_conf() {
  drush_print("inside magical pre-sql-conf hook");
}

function drush_magical_post_sql_conf() {
  drush_print("inside magical post-sql-conf hook");
}

Now if you call drush sql-conf you won't see anything special, but if you call drush --context=magical sql-conf, you should see both of your hooks fire. Nifty.

Step 2: Add some context selectors to your drushrc.php file:

$options['context-selectors'] = array(
  array( 'selectors' => array('xyzzy' => 1), 'context' => 'magical' ),
  'drush_test_magical',
);

function drush_test_magical() {
  $result = array();
  
  if (drush_get_option('magical') != NULL) {
    $result[] = 'magical';
  }
  
  return $result;
}

This example shows the two kinds of context selectors. A selector array contains a list of options with required values and a context name, whereas a selector string is the name of a php function somewhere that can do any test it likes to apply contexts. The return code is an array of context names. Now, drush --xyzzy=1 sql-conf or drush --magical=anything sql-conf will fire your hooks.

Step 3: Add a context definition.

$context['magical'] = array(
  'options' => array( 'v' => TRUE, 'd' => TRUE ),
  'hooks' => 'magical',
);

This perhaps should have been the first step; however, an empty or missing context definition defaults to a simple context that defines no options, and defines a single hook with the same name as the context. If you add the above definition to your drushrc.php file and re-run any of the tests above, you will see that your hooks fire, and in addition, 'verbose' and 'debug' are defined, so you will also see a list of all of your hook opportunities for sql-conf. If you change 'hooks' from 'magical' to 'mystical' and run again, then you will notice that the 'magical' hooks are no longer firing, but there are a number of hooks shown in the output of the hook opportunities code containing 'mystical' in their function names.

To make full use of this with sql-sync and rsync will require a separate patch to make those functions more hook-able. I'd like to do that as a separate step after this basic functionality is reviewed and vetted.

Okay, I can agree to your technique. The meta-info file needs to be considered twice, though: once before the commandlist is built, so it can include a file that defines commands, and once after the user-specified command is selected, so that additional hook functions can be defined based on the command parameters.

I suppose, though, that since that would be complicated (the later half), it might be better to just settle for:

function drush_mynamespace_pre_somecommand() {
  if (myconditions()) {
    // hook!
  }
}

I can go for that. I'll roll together the first half. Before drush adds a namespace and includes a file, it will look for a similarly-named file in the same folder. If found, that file will be included first, and a well-known function name inside it will be executed. Iff the result of the function is TRUE, then the commandlist processing will happen as usual. Otherwise, that file will be skipped.

If anyone has an opinion on the naming convention, let me know; otherwise I'll pick something and post a patch shortly.

Yes, I think that code is better. How about $namespace_drush_load_status(), though, for better alignment with its function? It could be stored in $namespace.load.status.inc.

If you prefer brevity, then I'll stick with $namespace_drush_status() and $namespace.status.inc.

@anarcat: You're right, the requirements on this issue are getting confused. There are a bunch of features represented here; let's take a step back and list them:

1. Use options to turn off existing commandfiles
2. Use options to add additional commandfiles or hooks (dynamic namespaces)
3. Use php code instead of options to do 1. or 2.
4. Use command-specific options or alias-defined options to do 1. or 2.
5. Turn commandfiles off before they are ever included (avoid defining duplicate functions)
6. Define options through metadata instead of php code
7. Define hook functions in drushrc.php
8. Use a meta-inf file to disable commandfiles

My patch in #1 provided a mechanism to do everything except 1. and 8.

Adrian did not think it was necessary to be able to dynamically add hooks; he preferred using the existing namespace = commandfile = hook association that drush currently provides, and wants a mechanism to just turn off existing commandfiles before they are loaded (1. and 5.) In #4, I think we agreed that meta-inf files are not flexible enough; therefore code is needed (3. is required, 8. is superfluous).

To answer the question in #6, in #2, Adrian was pointing out that options can be added via code during their init functions, so he felt that it was overkill to allow them to be defined using metadata in a drush configuration file. I kind of like this feature; it is analogous to the command-specific options.

In #3, I gave up on the idea of turning off hooks via command-specific or alias-specified options (feature 4.), since you can also get this behavior just by wrapping every hook in an 'if' statement. However, I think that turning hooks on and off is what this feature is all about, so in the end I think I'd be a little dissatisfied if hooks could be switched during commandfile collection, but not during command processing (when command-specific and alias-defined options are available).

At the moment, I'm thinking of removing 2. and adding 1. to my patch. I really want to keep 4. It is unclear to me whether we need 5.; if we do not, then we don't need an extra .inc file, we can just call a well-known function that is defined in the drush.inc file.

I'm still on the fence about 6.; I might try to keep this feature if I can do it in a simpler way, or at least do it in a way that is not called "contexts". The idea from fabrique is that you can have a simple name (a "context") that defines a set of options and hooks. Doing this easily in metadata is useful, I think.

Defining hooks in the drushrc.php was really just one example usage, one that I thought was easy to understand and describe. It may very well be undesirable, but in any event, nothing in my previous patch or my next patch will prevent or require code in drushrc.php.

I don't think we need 8.

Okay, I like that quite a bit. There's only one limitation with it. If there is an option that is defined in a drush configuration file that is stored in a Drupal site folder, then that option will not be defined until DRUSH_BOOTSTRAP_DRUPAL_SITE, but at this point you will have already missed all of the modules that had their load_check run during an earlier phase.

Here is a oh-so-slightly-more complicated version that retries the load test on every phase. If this satisfies the things you need, I'll open a new issue to add the code to allow this all to work in the case of drush sql-sync mydev mylive, which is requirement 4 above. n.b. the options defined in 'mydev' and 'mylive' are currently not applied until after the sql-sync command is invoked (e.g. 'type' => 'dev' and 'type' => 'live', defined in 'mydev' and 'mylive', respectively, will define 'source-type' and 'target-type' as 'dev' and 'live', respectively, after sql-sync evaluates its parameters).

I'm glad that #9 works well for everyone and is committed. I guess I'll leave this open for follow-on patches, although I'm not quite ready to do them yet.

Removing the "drush-3.0" tag, as follow-on changes are not necessary for 3.0-stable.

I'm just going to mark this "fixed". The important part went in with #12. I don't want named contexts any more. An alias already functions in part like a named context. There are a couple of things that are, perhaps, missing: having --option1 and --option2 imply (add) an --option3 when used together, and the ability for an option to "turn on" a hook dynamically. If we can do the later, then the former can be accomplished in code per #2, and per #8, I'm not sure we need dynamic hooks. If I change my mind later, I'll open a new issue about dynamic hooks.

Also, renaming so that the title matches what was committed.