Extension:Ask

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

Requirements
Ask 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 Ask/Ask.php. This file includes an autoloader that registers all the classes of the library.

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 two ways:

Standard PHPUnit fashion

There is a phpunit.xml.dist config file in the root directory of the Ask library. This means you can simply run "phpunit" in the root directory or run "phpunit -c /path/to/phpunit.xml.dist" from anywhere.


 * As MediaWiki extension tests

When Ask is registered 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 the library is loaded as extension.

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.