001/* An actor that converts tokens into expressions.
002
003 @Copyright (c) 1998-2014 The Regents of the University of California.
004 All rights reserved.
005
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the
009 above copyright notice and the following two paragraphs appear in all
010 copies of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024
025 PT_COPYRIGHT_VERSION 2
026 COPYRIGHTENDKEY
027 */
028package ptolemy.actor.lib.conversions;
029
030import java.util.HashSet;
031import java.util.Set;
032
033import ptolemy.data.StringToken;
034import ptolemy.data.type.BaseType;
035import ptolemy.data.type.TypeConstant;
036import ptolemy.graph.Inequality;
037import ptolemy.kernel.CompositeEntity;
038import ptolemy.kernel.util.IllegalActionException;
039import ptolemy.kernel.util.NameDuplicationException;
040
041///////////////////////////////////////////////////////////////////
042//// TokenToExpression
043
044/**
045 This actor reads a token from the input port and outputs a string token
046 whose value is an expression that can be parsed to yield the input token.
047 For example, if the input is itself a string token, the output will be a
048 new string token whose value is the value of the input string token surrounded
049 by double quotation marks. The input data type is undeclared, so this actor
050 can accept any input. If the input known to be absent, this actor outputs
051 a string "absent".<p>
052 This actor accepts any type of data on its input port, therefore it
053 doesn't declare a type, but lets the type resolution algorithm find
054 the least fixed point. If backward type inference is enabled, and
055 no input type has been declared, the input is constrained to be
056 equal to <code>BaseType.GENERAL</code>. This will result in upstream
057 ports resolving to the most general type rather than the most specific.
058 </p>
059
060 @author  Steve Neuendorffer, Haiyang Zheng
061 @version $Id$
062 @since Ptolemy II 2.1
063 @Pt.ProposedRating Yellow (neuendor)
064 @Pt.AcceptedRating Red (liuj)
065 */
066public class TokenToExpression extends Converter {
067    /** Construct an actor with the given container and name.
068     *  @param container The container.
069     *  @param name The name of this actor.
070     *  @exception IllegalActionException If the actor cannot be contained
071     *   by the proposed container.
072     *  @exception NameDuplicationException If the container already has an
073     *   actor with this name.
074     */
075    public TokenToExpression(CompositeEntity container, String name)
076            throws IllegalActionException, NameDuplicationException {
077        super(container, name);
078
079        input.setTypeEquals(BaseType.UNKNOWN);
080        output.setTypeEquals(BaseType.STRING);
081    }
082
083    ///////////////////////////////////////////////////////////////////
084    ////                         public methods                    ////
085
086    /** Output a string token whose value is an expression representing
087     *  the value of the input token. If the input known to be absent,
088     *  this actor outputs a string "absent".
089     *  @exception IllegalActionException If there's no director.
090     */
091    @Override
092    public void fire() throws IllegalActionException {
093        super.fire();
094        if (input.hasToken(0)) {
095            String string = input.get(0).toString();
096            output.broadcast(new StringToken(string));
097        } else {
098            output.broadcast(new StringToken("absent"));
099        }
100    }
101
102    ///////////////////////////////////////////////////////////////////
103    ////                         protected methods                 ////
104
105    /** Set the input port greater than or equal to
106     *  <code>BaseType.GENERAL</code> in case backward type inference is
107     *  enabled and the input port has no type declared.
108     *
109     *  @return A set of inequalities.
110     */
111    @Override
112    protected Set<Inequality> _customTypeConstraints() {
113        HashSet<Inequality> result = new HashSet<Inequality>();
114        if (isBackwardTypeInferenceEnabled()
115                && input.getTypeTerm().isSettable()) {
116            result.add(new Inequality(new TypeConstant(BaseType.GENERAL),
117                    input.getTypeTerm()));
118        }
119        return result;
120    }
121
122}