<?php

/*

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 *

 * This software consists of voluntary contributions made by many individuals

 * and is licensed under the LGPL. For more information, see

 * <http://www.doctrine-project.org>.

 */

namespace Doctrine\ORM\Query;

/**

 * This class is used to generate DQL expressions via a set of PHP static functions

 *

 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL

 * @link    www.doctrine-project.org

 * @since   2.0

 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>

 * @author  Jonathan Wage <jonwage@gmail.com>

 * @author  Roman Borschel <roman@code-factory.org>

 * @author  Benjamin Eberlei <kontakt@beberlei.de>

 * @todo Rename: ExpressionBuilder

 */

class Expr

{

    /**

     * Creates a conjunction of the given boolean expressions.

     *

     * Example:

     *

     *     [php]

     *     // (u.type = ?1) AND (u.role = ?2)

     *     $expr->andX('u.type = ?1', 'u.role = ?2'));

     *

     * @param mixed $x Optional clause. Defaults = null, but requires

     *                 at least one defined when converting to string.

     * @return Expr\Andx

     */

    public function andX($x = null)

    {

        return new Expr\Andx(func_get_args());

    }

    /**

     * Creates a disjunction of the given boolean expressions.

     *

     * Example:

     *

     *     [php]

     *     // (u.type = ?1) OR (u.role = ?2)

     *     $q->where($q->expr()->orX('u.type = ?1', 'u.role = ?2'));

     *

     * @param mixed $x Optional clause. Defaults = null, but requires

     *                 at least one defined when converting to string.

     * @return Expr\Orx

     */

    public function orX($x = null)

    {

        return new Expr\Orx(func_get_args());

    }

    /**

     * Creates an ASCending order expression.

     *

     * @param $sort

     * @return OrderBy

     */

    public function asc($expr)

    {

        return new Expr\OrderBy($expr, 'ASC');

    }

    /**

     * Creates a DESCending order expression.

     *

     * @param $sort

     * @return OrderBy

     */

    public function desc($expr)

    {

        return new Expr\OrderBy($expr, 'DESC');

    }

    /**

     * Creates an equality comparison expression with the given arguments.

     *

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> = <right expr>. Example:

     *

     *     [php]

     *     // u.id = ?1

     *     $expr->eq('u.id', '?1');

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function eq($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::EQ, $y);

    }

    /**

     * Creates an instance of Expr\Comparison, with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> <> <right expr>. Example:

     *

     *     [php]

     *     // u.id <> ?1

     *     $q->where($q->expr()->neq('u.id', '?1'));

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function neq($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::NEQ, $y);

    }

    /**

     * Creates an instance of Expr\Comparison, with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> < <right expr>. Example:

     *

     *     [php]

     *     // u.id < ?1

     *     $q->where($q->expr()->lt('u.id', '?1'));

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function lt($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::LT, $y);

    }

    /**

     * Creates an instance of Expr\Comparison, with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> <= <right expr>. Example:

     *

     *     [php]

     *     // u.id <= ?1

     *     $q->where($q->expr()->lte('u.id', '?1'));

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function lte($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::LTE, $y);

    }

    /**

     * Creates an instance of Expr\Comparison, with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> > <right expr>. Example:

     *

     *     [php]

     *     // u.id > ?1

     *     $q->where($q->expr()->gt('u.id', '?1'));

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function gt($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::GT, $y);

    }

    /**

     * Creates an instance of Expr\Comparison, with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> >= <right expr>. Example:

     *

     *     [php]

     *     // u.id >= ?1

     *     $q->where($q->expr()->gte('u.id', '?1'));

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Comparison

     */

    public function gte($x, $y)

    {

        return new Expr\Comparison($x, Expr\Comparison::GTE, $y);

    }

    /**

     * Creates an instance of AVG() function, with the given argument.

     *

     * @param mixed $x Argument to be used in AVG() function.

     * @return Expr\Func

     */

    public function avg($x)

    {

        return new Expr\Func('AVG', array($x));

    }

    /**

     * Creates an instance of MAX() function, with the given argument.

     *

     * @param mixed $x Argument to be used in MAX() function.

     * @return Expr\Func

     */

    public function max($x)

    {

        return new Expr\Func('MAX', array($x));

    }

    /**

     * Creates an instance of MIN() function, with the given argument.

     *

     * @param mixed $x Argument to be used in MIN() function.

     * @return Expr\Func

     */

    public function min($x)

    {

        return new Expr\Func('MIN', array($x));

    }

    /**

     * Creates an instance of COUNT() function, with the given argument.

     *

     * @param mixed $x Argument to be used in COUNT() function.

     * @return Expr\Func

     */

    public function count($x)

    {

        return new Expr\Func('COUNT', array($x));

    }

    /**

     * Creates an instance of COUNT(DISTINCT) function, with the given argument.

     *

     * @param mixed $x Argument to be used in COUNT(DISTINCT) function.

     * @return string

     */

    public function countDistinct($x)

    {

        return 'COUNT(DISTINCT ' . implode(', ', func_get_args()) . ')';

    }

    /**

     * Creates an instance of EXISTS() function, with the given DQL Subquery.

     *

     * @param mixed $subquery DQL Subquery to be used in EXISTS() function.

     * @return Expr\Func

     */

    public function exists($subquery)

    {

        return new Expr\Func('EXISTS', array($subquery));

    }

    /**

     * Creates an instance of ALL() function, with the given DQL Subquery.

     *

     * @param mixed $subquery DQL Subquery to be used in ALL() function.

     * @return Expr\Func

     */

    public function all($subquery)

    {

        return new Expr\Func('ALL', array($subquery));

    }

    /**

     * Creates a SOME() function expression with the given DQL subquery.

     *

     * @param mixed $subquery DQL Subquery to be used in SOME() function.

     * @return Expr\Func

     */

    public function some($subquery)

    {

        return new Expr\Func('SOME', array($subquery));

    }

    /**

     * Creates an ANY() function expression with the given DQL subquery.

     *

     * @param mixed $subquery DQL Subquery to be used in ANY() function.

     * @return Expr\Func

     */

    public function any($subquery)

    {

        return new Expr\Func('ANY', array($subquery));

    }

    /**

     * Creates a negation expression of the given restriction.

     *

     * @param mixed $restriction Restriction to be used in NOT() function.

     * @return Expr\Func

     */

    public function not($restriction)

    {

        return new Expr\Func('NOT', array($restriction));

    }

    /**

     * Creates an ABS() function expression with the given argument.

     *

     * @param mixed $x Argument to be used in ABS() function.

     * @return Expr\Func

     */

    public function abs($x)

    {

        return new Expr\Func('ABS', array($x));

    }

    /**

     * Creates a product mathematical expression with the given arguments.

     *

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> * <right expr>. Example:

     *

     *     [php]

     *     // u.salary * u.percentAnualSalaryIncrease

     *     $q->expr()->prod('u.salary', 'u.percentAnualSalaryIncrease')

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Math

     */

    public function prod($x, $y)

    {

        return new Expr\Math($x, '*', $y);

    }

    /**

     * Creates a difference mathematical expression with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> - <right expr>. Example:

     *

     *     [php]

     *     // u.monthlySubscriptionCount - 1

     *     $q->expr()->diff('u.monthlySubscriptionCount', '1')

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Math

     */

    public function diff($x, $y)

    {

        return new Expr\Math($x, '-', $y);

    }

    /**

     * Creates a sum mathematical expression with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> + <right expr>. Example:

     *

     *     [php]

     *     // u.numChildren + 1

     *     $q->expr()->diff('u.numChildren', '1')

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Math

     */

    public function sum($x, $y)

    {

        return new Expr\Math($x, '+', $y);

    }

    /**

     * Creates a quotient mathematical expression with the given arguments.

     * First argument is considered the left expression and the second is the right expression.

     * When converted to string, it will generated a <left expr> / <right expr>. Example:

     *

     *     [php]

     *     // u.total / u.period

     *     $expr->quot('u.total', 'u.period')

     *

     * @param mixed $x Left expression

     * @param mixed $y Right expression

     * @return Expr\Math

     */

    public function quot($x, $y)

    {

        return new Expr\Math($x, '/', $y);

    }

    /**

     * Creates a SQRT() function expression with the given argument.

     *

     * @param mixed $x Argument to be used in SQRT() function.

     * @return Expr\Func

     */

    public function sqrt($x)

    {

        return new Expr\Func('SQRT', array($x));

    }

    /**

     * Creates an IN() expression with the given arguments.

     *

     * @param string $x Field in string format to be restricted by IN() function

     * @param mixed $y Argument to be used in IN() function.

     * @return Expr\Func

     */

    public function in($x, $y)

    {

        if (is_array($y)) {

            foreach ($y as &$literal) {

                if ( ! ($literal instanceof Expr\Literal)) {

                    $literal = $this->_quoteLiteral($literal);

                }

            }

        }

        return new Expr\Func($x . ' IN', (array) $y);

    }

    /**

     * Creates a NOT IN() expression with the given arguments.

     *

     * @param string $x Field in string format to be restricted by NOT IN() function

     * @param mixed $y Argument to be used in NOT IN() function.

     * @return Expr\Func

     */

    public function notIn($x, $y)

    {

        if (is_array($y)) {

            foreach ($y as &$literal) {

                if ( ! ($literal instanceof Expr\Literal)) {

                    $literal = $this->_quoteLiteral($literal);

                }

            }

        }

        return new Expr\Func($x . ' NOT IN', (array) $y);

    }

    /**

     * Creates an IS NULL expression with the given arguments.

     *

     * @param string $x Field in string format to be restricted by IS NULL

     * @return string

     */

    public function isNull($x)

    {

        return $x . ' IS NULL';

    }

    /**

     * Creates an IS NOT NULL expression with the given arguments.

     *

     * @param string $x Field in string format to be restricted by IS NOT NULL

     * @return string

     */

    public function isNotNull($x)

    {

        return $x . ' IS NOT NULL';

    }