Extension:Ask

Ask is a small library containing a PHP and JavaScript implementation of the Ask query language.

Requirements
Diff requires:


 * PHP 5.3 or above
 * (If used as MediaWiki extension: MediaWiki 1.16 or later)

As MediaWiki extension
Once you have downloaded the code, place the Ask directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

As standalone library
Include Diff/Ask.php. This file includes an autoloader allowing you to directly reference the diff classes without first including their files. If you want to use your own autoloader, you can find the list of diff classes in Ask/Ask.classes.php.

Structure
The Ask library defines the Ask query language. Its important components are:


 * Ask\Language - everything part of the ask language itself
 * Ask\Language\Description - descriptions (aka concepts)
 * Ask\Language\Option - QueryOptions object and its parts
 * Ask\Language\Selection - selection requests
 * Ask\Language\Query.php - the object defining what a query is

Description
Each query has a single description which specifies which entities match. This is similar to the WHERE part of an SQL string. There different types of descriptions are listed below. Since several types of descriptions can be composed out of one or more sub descriptions, tree like structures can be created.


 * Description - abstract base class
 * AnyValue - A description that matches any object
 * Conjunction - Description of a collection of many descriptions, all of which must be satisfied (AND)
 * Disjunction - Description of a collection of many descriptions, at least one of which must be satisfied (OR)
 * SomeProperty - Description of a set of instances that have an attribute with some value that fits another (sub)description
 * ValueDescription - Description of one data value, or of a range of data values

All descriptions reside in the Ask\Language\Description namespace.

Option
The options a query consist out of are defined by the  class. This class contains limit, offset and sorting options.

Sorting options are defined by the  class, which contains a list of   objects.

All options related classes reside in the Ask\Language\Option namespace.

Selection
Specifying what information a query should select from matching entities is done via the selection requests in the query object. Selection requests are thus akin to the SELECT part of an SQL string. They thus have no effect on which entities match the query and are returned. All types of selection request implement abstract base class SelectionRequest and can be found in the Ask\Language\Selection namespace.

Usage

 * A query for the first hunded entities that are compared


 * A query with an offset of 50


 * A query to get the cost of the first hundered entities that have a cost property

This is assuming 'p42' is an identifier for a cost property.


 * A query to get the first hundred entities that have 9000.1 as value for their cost property.

This is assuming 'p42' is an identifier for a cost property.


 * A query getting the hundred entities with highest cost, highest cost first

This is assuming 'p42' is an identifier for a cost property.


 * A query to get the hundred first entities that have a cost either equal to 42 or bigger than 9000

This is assuming 'p42' is an identifier for a cost property.

Tests
Development guidelines for Ask state that all code should have associated tests; TDD is encouraged. All tests are in the group 'Ask'. The minimum PHPUnit version is 3.7. There are no further requirements for the tests that deviate from the production code requirements.

The tests can be run in several ways:


 * As MediaWiki extension tests

When Ask is regeistered as a MediaWiki extension, it will register its tests using the MediaWiki PHPUnit tests hook. You can thus run them via mediawiki-root/tests/phpunit/phpunit.php when library is loaded as extension.

As of April 2013, MediaWiki does not allow registering a directory of tests and requires a manually maintained list of the Ask tests for this to work. The list can be found in Ask.mw.php and should be updated when new tests are added.


 * Via the standalone test runner

The PHPunit tests are also registered by a standalone runner which can be found at ask-root/Tests/Phpunit/phpunit.php


 * Via your own runner

If you want to use your own runner, that is also possible of course. You will need to do the following things in your code:


 * Register the ask-root/Tests/Phpunit directory with PHPunit as containing tests you want to run.
 * Register the production code classes with an autoloader of your choice. A class to file map can be obtained from Ask.classes.php in the library root.
 * Register the test code classes (such as abstract base classes) with an autoloader of your choice. A class to file map can be obtained from ask-root/Tests/AskTestClasses.php.

Version
This is a copy of the release notes file on Git, which might be more up to date than this page.

TODO

Internationalization
is fully internationalized. Translation of messages is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Authors
Ask has been written by Jeroen De Dauw as Wikimedia Germany employee for the Wikidata project.