/*
 * @author Ranides Atterwim {@literal <ranides@gmail.com>}
 * @copyright Ranides Atterwim
 * @license WTFPL
 * @url http://ranides.net/projects/assira
 */
package net.ranides.assira.reflection;

import net.ranides.assira.reflection.impl.AHints;

/**
 * This interface represents type hints used for filtering IElements collection.
 *
 * It stores two sets of attributes.
 * First set contains required attributes.
 * Second set contains not allowed attributes.
 *
 * Some collections use information about visibility and DECLARED attribute
 * to enable or disable recursive scan. Generally, if you require non-public visibility,
 * result will contain inherited members, until you require DECLARED attribute too.
 *
 * @author Ranides Atterwim {@literal <ranides@gmail.com>}
 */
public interface IHints {

    /**
     * Returns immutable empty set of hints
     *
     * @return IHints
     */
    static IHints none() {
        return AHints.$none();
    }

    /**
     * Returns mutable set of required attributes
     *
     * @return IAttributes
     */
    IAttributes require();

    /**
     * Adds provided attribute to required set.
     *
     * @param attr attr
     * @return this
     */
    IHints require(IAttribute attr);

    /**
     * Adds provided attributes to required set.
     *
     * @param attrs attrs
     * @return this
     */
    IHints require(IAttributes attrs);

    /**
     * Returns mutable set of prohibited attributes
     *
     * @return IAttributes
     */
    IAttributes discard();

    /**
     * Adds provided attribute to discard set.
     *
     * @param attr attr
     * @return this
     */
    IHints discard(IAttribute attr);

    /**
     * Adds provided attributes to discard set.
     *
     * @param attrs attrs
     * @return this
     */
    IHints discard(IAttributes attrs);

    /**
     * Changes attributes stored inside this hints, by copying values from provided hints
     *
     * @param value value
     * @return this
     */
    IHints replace(IHints value);

}
