Jeroen De Dauw has uploaded a new change for review. https://gerrit.wikimedia.org/r/73718
Change subject: Add docs to README file ...................................................................... Add docs to README file Change-Id: I7d15da322993e1b579483b9fdb9f9d811adc3783 --- M README.md 1 file changed, 153 insertions(+), 2 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Ask refs/changes/18/73718/1 diff --git a/README.md b/README.md index d3762cd..58f421f 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,161 @@ Load all dependencies and the load the Ask library by including its entry point: Ask.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 <code>QueryOptions</code> class. This class +contains limit, offset and sorting options. + +Sorting options are defined by the <code>SortOptions</code> class, which contains a list of +<code>SortExpression</code> 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 -The [extension page on mediawiki.org](https://www.mediawiki.org/wiki/Extension:Ask) -contains the documentation and examples for this library. +#### A query for the first hunded entities that are compared + +```php +use Ask\Language\Query; +use Ask\Language\Description\AnyValue; +use Ask\Language\Option\QueryOptions; + +$myAwesomeQuery = new Query( + new AnyValue(), + array(), + new QueryOptions( 100, 0 ) +); +``` + +#### A query with an offset of 50 + +```php +$myAwesomeQuery = new Query( + new AnyValue(), + array(), + new QueryOptions( 100, 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. + +```php +$awesomePropertyId = new PropertyValue( 'p42' ); + +$myAwesomeQuery = new Query( + new SomeProperty( $awesomePropertyId, new AnyValue() ), + array( + new PropertySelection( $awesomePropertyId ) + ), + new QueryOptions( 100, 0 ) +); +``` + +#### 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. + +```php +$awesomePropertyId = new PropertyValue( 'p42' ); +$someCost = new NumericValue( 9000.1 ); + +$myAwesomeQuery = new Query( + new SomeProperty( $awesomePropertyId, new ValueDescription( $someCost ) ), + array(), + new QueryOptions( 100, 0 ) +); +``` + +#### A query getting the hundred entities with highest ''cost'', highest ''cost'' first + +This is assuming 'p42' is an identifier for a ''cost'' property. + +```php +$awesomePropertyId = new PropertyValue( 'p42' ); + +$myAwesomeQuery = new Query( + new AnyValue(), + array(), + new QueryOptions( + 100, + 0, + new SortOptions( array( + new PropertyValueSortExpression( $awesomePropertyId, SortExpression::DESCENDING ) + ) ) + ) +); +``` + +#### 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. + +```php +$awesomePropertyId = new PropertyValue( 'p42' ); +$costOf42 = new NumericValue( 42 ); +$costOf9000 = new NumericValue( 9000 ); + +$myAwesomeQuery = new Query( + new SomeProperty( + $awesomePropertyId, + new Disjunction( array( + new ValueDescription( $costOf42 ), + new ValueDescription( $costOf9000, ValueDescription::COMP_GRTR ), + ) ) + ), + array(), + new QueryOptions( 100, 0 ) +); +``` + +## Tests + +This library comes with a set up PHPUnit tests that cover all non-trivial code. You can run these +tests using the PHPUnit configuration file found in the root directory. The tests can also be run +via TravisCI, as a TravisCI configuration file is also provided in the root directory. + +## Authors + +Ask has been written by [Jeroen De Dauw](https://www.mediawiki.org/wiki/User:Jeroen_De_Dauw) +as [Wikimedia Germany](https://wikimedia.de) employee for the [Wikidata project](https://wikidata.org/). ## Links -- To view, visit https://gerrit.wikimedia.org/r/73718 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I7d15da322993e1b579483b9fdb9f9d811adc3783 Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/Ask Gerrit-Branch: master Gerrit-Owner: Jeroen De Dauw <jeroended...@gmail.com> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
