offapi/com/sun/star/util/XStringSubstitution.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21  module com {  module sun {  module star {  module  util {
  22
  23 /** A common interface for substituting string variables with
  24     other strings.
  25
  26     <p>
  27     The substitution algorithm and the syntax for a string variable are
  28     not part of this interface definition.  Please look at the documentation
  29     of the implementation that must specify these parameters.
  30     </p>
  31
  32     @since OOo 1.1.2
  33 */
  34 published interface XStringSubstitution : com::sun::star::uno::XInterface
  35 {
  36     /** Exchanges variables inside a given text with a substitution text
  37         defined for the variables.
  38
  39         <p>
  40         The method iterates through its internal variables list to match the
  41         variables in the given string. A match replaces the variable with the
  42         string defined for this variable. If no variable can be found in the string
  43         it will be returned unchanged. The behavior if a variable is found in
  44         the string but it is unknown for the implementation depends on the parameter
  45         bSubstRequired.
  46         </p>
  47
  48         @param aText
  49             A string containing variables that should be substituted.
  50
  51         @param bSubstRequired
  52             Specifies if a successful substitution is required. The
  53             function throws a com::sun::star::container::NoSuchElementException
  54             if it finds a variable that is unknown. In this case it is possible
  55             that the returned string would not be what the caller expected!
  56
  57         @return
  58             Returns a string based on <var>aText</var> where all variables were
  59             exchanged with their value defined at calling time.
  60     */
  61     string substituteVariables( [in] string aText, [in] boolean bSubstRequired )
  62         raises( com::sun::star::container::NoSuchElementException );
  63
  64     /** Tries to replace parts of aText with variables that represents
  65         these sub strings.
  66
  67         <p>
  68         The method iterates through its internal variable list and tries to match
  69         parts of the given string Tries to replace parts of <var>aText</var> with
  70         variables that represents these sub strings.If more than one variable
  71         matches the one with the longest matching sub string will be chosen.
  72         </p>
  73
  74         @param aText
  75             A string where known substrings should be replaced by variables.
  76
  77         @return
  78             Returns the resubstituted string with variables for all parts
  79             that could be replaced. The unchanged argument will be returned
  80             if nothing can be resubstituted.
  81     */
  82
  83     string reSubstituteVariables( [in] string aText );
  84
  85     /** Returns the current value of a variable.
  86
  87         <p>
  88         The method iterates through its internal variable list and tries to
  89         find the given variable. If the variable is unknown a
  90         com::sun::star::container::NoSuchElementException
  91         is thrown.
  92         </p>
  93
  94         @param variable
  95             The name of a variable.
  96
  97         @return
  98             Returns a string that represents the variable. If the
  99             variable is unknown a com::sun::star::container::NoSuchElementException
 100             is thrown.
 101     */
 102     string getSubstituteVariableValue( [in] string variable )
 103         raises (::com::sun::star::container::NoSuchElementException );
 104 };
 105
 106
 107 }; }; }; };
 108
 109 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */