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 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>

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>

h2. TransformUtils

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>