<?php
/**
 * Copyright 2016 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\Cloud\Language;

use Google\Cloud\Core\CallTrait;

/**
 * Annotations represent the result of a request against the
 * [Google Cloud Natural Language API](https://cloud.google.com/natural-language/docs).
 *
 * This class is created internally by
 * {@see Google\Cloud\Language\LanguageClient} and is used to
 * represent various document analyzation results. It should not be instantiated
 * externally.
 *
 * Annotations are returned by
 * {@see Google\Cloud\Language\LanguageClient::analyzeEntities()},
 * {@see Google\Cloud\Language\LanguageClient::analyzeSentiment()},
 * {@see Google\Cloud\Language\LanguageClient::analyzeEntitySentiment()},
 * {@see Google\Cloud\Language\LanguageClient::analyzeSyntax()} and
 * {@see Google\Cloud\Language\LanguageClient::annotateText()}.
 *
 * Example:
 * ```
 * use Google\Cloud\Language\LanguageClient;
 *
 * $language = new LanguageClient();
 *
 * $annotation = $language->annotateText('Google Cloud Platform is a powerful tool.');
 * ```
 *
 * @method sentences() {
 *     Returns an array of sentences found in the document.
 *
 *     Example:
 *     ```
 *     foreach ($annotation->sentences() as $sentence) {
 *         echo $sentence['text']['content'];
 *     }
 *     ```
 *
 *     @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Sentence Sentence type documentation
 *
 *     @return array|null
 * }
 * @method tokens() {
 *     Returns an array of tokens found in the document.
 *
 *     Example:
 *     ```
 *     foreach ($annotation->tokens() as $token) {
 *         echo $token['text']['content'];
 *     }
 *     ```
 *
 *     @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Token Token type documentation
 *
 *     @return array|null
 * }
 * @method entities() {
 *     Returns an array of entities found in the document.
 *
 *     Example:
 *     ```
 *     foreach ($annotation->entities() as $entity) {
 *         echo $entity['type'];
 *     }
 *     ```
 *
 *     @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Entity Entity type documentation
 *
 *     @return array|null
 * }
 * @method categories() {
 *     Returns an array of categories representing the input document.
 *
 *     Example:
 *     ```
 *     foreach ($annotation->categories() as $category) {
 *         echo $category['name'];
 *     }
 *     ```
 *
 *     @codingStandardsIgnoreStart
 *     @see https://cloud.google.com/natural-language/docs/reference/rest/v1beta2/ClassificationCategory Classification category documentation
 *     @codingStandardsIgnoreEnd
 *
 *     @return array|null
 * }
 * @method language() {
 *     Returns the language of the document.
 *
 *     Example:
 *     ```
 *     echo $annotation->language();
 *     ```
 *
 *     @return string|null
 * }
 */
class Annotation
{
    use CallTrait;

    /**
     * @var array The annotation's metadata.
     */
    private $info;

    /**
     * Create an annotation.
     *
     * @param array $info [optional] The annotation's metadata.
     */
    public function __construct(array $info = [])
    {
        $this->info = $info;
    }

    /**
     * Returns the full response from the API.
     *
     * Example:
     * ```
     * $info = $annotation->info();
     * ```
     *
     * @codingStandardsIgnoreStart
     * @see https://cloud.google.com/natural-language/docs/reference/rest/v1/documents/annotateText#response-body Annotate Text documentation
     * @codingStandardsIgnoreEnd
     *
     * @return array
     */
    public function info()
    {
        return $this->info;
    }

    /**
     * Returns the sentiment of the document.
     *
     * Example:
     * ```
     * $sentiment = $annotation->sentiment();
     *
     * if ($sentiment['score'] > 0) {
     *     echo 'This is a positive message.';
     * }
     * ```
     *
     * @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Sentiment Sentiment type documentation
     *
     * @return array|null
     */
    public function sentiment()
    {
        return isset($this->info['documentSentiment']) ? $this->info['documentSentiment'] : null;
    }

    /**
     * Returns an array of tokens filtered by the given tag.
     *
     * Example:
     * ```
     * $tokens = $annotation->tokensByTag('NOUN');
     *
     * foreach ($tokens as $token) {
     *     echo $token['lemma'];
     * }
     * ```
     *
     * @codingStandardsIgnoreStart
     * @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Token#Tag Token tags documentation
     * @codingStandardsIgnoreEnd
     *
     * @return array|null
     */
    public function tokensByTag($tag)
    {
        return $this->filter(
            $this->tokens(),
            ['partOfSpeech', 'tag'],
            $tag
        );
    }

    /**
     * Returns an array of tokens filtered by the given label.
     *
     * Example:
     * ```
     * $tokens = $annotation->tokensByLabel('P');
     *
     * foreach ($tokens as $token) {
     *     echo $token['lemma'];
     * }
     * ```
     *
     * @codingStandardsIgnoreStart
     * @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Token#Label Token labels documentation
     * @codingStandardsIgnoreEnd
     *
     * @return array|null
     */
    public function tokensByLabel($label)
    {
        return $this->filter(
            $this->tokens(),
            ['dependencyEdge', 'label'],
            $label
        );
    }

    /**
     * Returns an array of entities filtered by the given type.
     *
     * Example:
     * ```
     * $entities = $annotation->entitiesByType('PERSON');
     *
     * foreach ($entities as $entity) {
     *     echo $entity['name'];
     * }
     * ```
     *
     * @codingStandardsIgnoreStart
     * @see https://cloud.google.com/natural-language/docs/reference/rest/v1/Entity#Type Entity types documentation
     * @codingStandardsIgnoreEnd
     *
     * @return array|null
     */
    public function entitiesByType($type)
    {
        return $this->filter(
            $this->entities(),
            ['type'],
            $type
        );
    }

    /**
     * Filters an array of items based on the provided type.
     *
     * @param array $items The items to iterate.
     * @param array $path The path to the value to compare against the provided
     *        type.
     * @param string $type The type to filter on.
     * @return array|null
     */
    private function filter($items, $path, $type)
    {
        if (!$items) {
            return null;
        }

        return array_filter($items, function ($item) use ($path, $type) {
            $itemCopy = $item;

            // key into the value with the given path
            foreach ($path as $key) {
                $itemCopy = $itemCopy[$key];
            }

            if (strtolower($itemCopy) === strtolower($type)) {
                return $item;
            }
        });
    }
}
