Retrascope

h1. Utility Classes and Methods

{{toc}}

The HDL Retrascope project includes several classes for utility methods. It is supposed to use these methods for solving common small problems, like reading the file line by line, solving the constraint and so on.

This page contains a list of such method signatures with Javadoc headers sorted by classes.

h2. NodeUtils

Utility methods for operating with @ru.ispras.fortress.expression.Node@ class objects and it''s descendants.

<pre><code class="java">

  /**

   * Returns an equation {@code (nodes[0] == ... == nodes[n - 1])} expression

   * of the specified nodes.

   *

   * @param nodes Expressions to be combined.

   *

   * @return An equation of the specified nodes.

   *

   * @throws IllegalArgumentException when argument is either {@code null} or empty.

   */

  public static Node getEquation(final Node ... nodes)

</code></pre>

<pre><code class="java">

  /**

   * Returns a conjunction of the specified nodes.

   * @param nodes Nodes for conjunction.

   * @return Conjunction of specified nodes.

   * @throws IllegalArgumentException when argument is {@code null}.

   */

  public static Node getConjunction(final Node ... nodes)

</code></pre>

<pre><code class="java">

  /**

   * Returns a conjunction of non-empty collection of nodes.

   * <p>Repeated nodes will not appear in the result.</p>

   * @param nodes Nodes for conjunction.

   * @return Conjunction of nodes that are in the specified collection.

   * @throws IllegalArgumentException when argument is {@code null}.

   * @throws IllegalArgumentException when argument is empty.

   */

  public static Node getConjunction(final Collection<Node> nodes)

</code></pre>

<pre><code class="java">

  /**

   * Returns a disjunction of non-empty collection of nodes.

   * @param nodes Nodes for disjunction.

   * @return Disjunction of nodes that are in the specified collection.

   * @throws IllegalArgumentException when argument is {@code null}.

   * @throws IllegalArgumentException when argument is empty.

   */

  public static Node getDisjunction(final Collection<Node> nodes)

</code></pre>

<pre><code class="java">

  /**

   * Returns a collection of names for variables from the specified collection.

   *

   * @param nodes Collection of nodes.

   *

   * @return Collection of names for variable nodes from the specified collection.

   *

   * @throws IllegalArgumentException when argument is {@code null}.

   */

  public static Collection<String> getVariableNames(final Collection<? extends Node> nodes)

</code></pre>

<pre><code class="java">

/**

   * Casts the specified node to the specified data type.

   *

   * @param node Expression to be casted.

   * @param dataType Type to which the expression to be casted to.

   *

   * @return An expression which is equivalent to the specified node and has the specified type.

   *

   * @throws IllegalArgumentException when any of arguments is {@code null}.

   */

  public static Node castToDataType(final Node node, final DataType dataType)

</code></pre>

<pre><code class="java">

  /**

   * Splits the specified node into two parts - one that depends exactly from the specified

   * variables and another that does not depend.

   * @param node Node to be split.

   * @param variables Variables dependence to which is a splitting criterion.

   * @return Two nodes that being united (with AND) form a node that is equal to the specified one.

   *         The first one depends exactly from the specified variables the second does not depend

   *         from all of them.

   */

  public static Pair<Node, Node> splitByVar(final Node node, final Collection<NodeVariable> variables)

</code></pre>

<pre><code class="java">

  /**

   * Splits conjunction node into non-conjunction nodes.

   * @param node Node to be split.

   * @return Collection of nodes that being united by AND operation (a conjunction)

   *         forms an expression that is equivalent to the specified one.

   */

  public static Collection<Node> splitConjunction(final Node node)

</code></pre>

h2. ReadWriteUtils

Utility methods for reading from file, stream etc. and for writing to it.

<pre><code class="java">

/**

   * Returns reader for the specified stream object.

   * <p>Default charset is used for reading.</p>

   * @param stream Stream to be read.

   * @return Reader for the specified stream object.

   * @throws IllegalArgumentException when argument is {@code null}.

   */

  public static BufferedReader newBufferedReader(final InputStream stream)

</code></pre>

<pre><code class="java">

/**

   * Returns reader for the specified path object.

   * <p>Default charset is used for reading.</p>

   * @param path Path from which data to be read.

   * @return Reader for the specified path object.

   * @throws IllegalArgumentException when argument is {@code null}.

   * @throws RetrascopeRuntimeException when I/O error occurred.

   */

  public static BufferedReader newBufferedReader(final Path path)

</code></pre>

<pre><code class="java">

/**

   * Returns writer to the specified stream object.

   * <p>Default charset is used for writing.</p>

   * @param stream Stream to write to.

   * @return Writer to the specified stream object.

   * @throws IllegalArgumentException when argument is {@code null}.

   */

  public static BufferedWriter newBufferedWriter(final OutputStream stream)

</code></pre>

<pre><code class="java">

/**

   * Returns writer to the specified file object.

   * <p>Default charset is used for writing.</p>

   * @param file File to write to.

   * @return Writer to the specified file object.

   * @throws IllegalArgumentException when argument is {@code null}.

   * @throws RetrascopeRuntimeException when the specified file already contains data

   *         or when I/O error occurred.

   */

  public static BufferedWriter newBufferedWriter(final File file)

</code></pre>

<pre><code class="java">

/**

   * Returns writer to the specified path object.

   * @param path Path to write to.

   * @return Writer to the specified path object.

   * @throws IllegalArgumentException is {@code null}.

   * @throws RetrascopeRuntimeException when the specified file already exists

   *         or when an I/O error occurred.

   */

  public static BufferedWriter newBufferedWriter(final Path path)

</code></pre>

<pre><code class="java">

/**

   * Returns writer to the specified file object.

   * <p>Default charset is used for writing.</p>

   * @param file File to write to.

   * @return Writer to the specified file object.

   * @throws IllegalArgumentException when argument is {@code null}.

   */

  public static PrintWriter newPrintWriter(final File file)

</code></pre>

h2. SolverUtils

Utility methods for constraint and expression solving.

<pre><code class="java">

/**

   * Checks whether the specified expression is satisfiable.

   *

   * @param node Expression to be checked.

   * @return {@code true} if the expression is satisfiable or {@code false} otherwise.

   *

   */

  public static boolean isSat(final Node node)

</code></pre>

<pre><code class="java">

/**

   * Checks whether the specified logical expressions are compatible

   * {@code (getConjunction(nodes[0], ..., nodes[n-1]) is SAT)}.

   *

   * @param expressions Logical expressions to be checked.

   *

   * @return {@code true} if the specified expressions are compatible, {@code false} otherwise.

   */

  public static boolean areCompatible(final Node... expressions)

</code></pre>

<pre><code class="java">

/**

   * Checks whether the specified logical expressions are complete

   * {@code (!getComplement(nodes[0], ..., nodes[n-1]) is SAT)}.

   *

   * @param expressions Logical expressions to be checked.

   *

   * @return {@code true} if the specified expressions are complete, {@code false} otherwise.

   */

  public static boolean areComplete(final Node... expressions)

</code></pre>

<pre><code class="java">

/**

   * Solves the specified expression.

   *

   * @param node Expression to be solved.

   *

   * @return Result of solving.

   */

  public static SolverResult solve(final Node node)

</code></pre>

h2. TransformerUtils

Utility methods for transformation of expressions.

<pre><code class="java">

/**

   * Replace operations in expression with standard counterparts.

   * <p>Transforms nodes of the following kinds:

   * <ul>

   *   <li> EQ operation with more than 2 operands - to conjunction of 2-operand EQs;

   * </ul>

   * Wrapping method for {@code Transformer.standardize} method.

   * Uses it''s internal rules for additional replacements.</p>

   *

   * @see Transformer

   * @param node Expression to be transformed.

   * @return Expression with non-standard operations being replaced.

   */

  public static Node standardize(final Node node)

</code></pre>

<pre><code class="java">

  /**

   * Reduces the specified expression and tries to convert it to the specified data type.

   * <p>It is recommended to use this method for non-variable-dependent expressions

   * containing constants and operators.</p>

   * @param node Expression to be simplified and converted to the specified type.

   * @param dataType Data type to which the specified node should be converted.

   * @return Expression that is a simplified form of the specified node and is converted

   *         to the specified type.

   */

  public static Node reduce(final Node node, final DataType dataType)

</code></pre>

h2. ModelTransformUtils

Utility methods for models and model components transformation.

<pre><code class="java">

/**

   * Performs backward substitution on the specified nodes to the specified expression.

   *

   * <p>The substitution process moves in a backward direction (from last node of the list

   * to the first). The result is an expression where all the target variables that are

   * defined at least one {@link AssignmentContainer} node from the specified collection

   * will be substituted by the value expressions that are assigned to them.</p>

   *

   * @param blocks Blocks which should be used as a source of substitution.

   * @param node Expression to be transformed.

   *

   * @return Modified expression.

   */

  public static Node substituteBackward(

      final List<? extends AssignmentContainer> blocks,

      final Node node)

</code></pre>