(*
 * <COPYRIGHT>
 * Copyright 2002 Joachim Schrod Network and Publication Consultance GmbH, Gerd Stolpmann
 *
 * <GPL>
 * This file is part of WDialog.
 *
 * WDialog is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * WDialog is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with WDialog; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * </>
 *)

(* $Id: wd_var_functions.mli,v 1.3 2003/02/16 01:07:03 stolpmann Exp $
 * ----------------------------------------------------------------------
 *
 *)

(** This module defines the "variable functions" that can be called in
 * [$[...]] expressions. All these functions take formally a list of
 * [var_value] arguments and return a [var_value]. Actually, they are
 * often only defined for a certain number of arguments, and for arguments
 * of certain type.
 *
 * The functions raise a [Failure] exception if something is wrong.
 *)


open Wd_types

val size : dialog_type -> var_value list -> var_value
  (** Returns the size of the single argument, which may be a [String_value],
   * [Enum_value], [Dyn_enum_value], or an [Alist_value].
   * The returned size is encoded as [String_value].
   *)

val add : dialog_type -> var_value list -> var_value
  (** Adds the numbers encoded as [String_value], and returns the sum as
   * [String_value].
   *)

val sub : dialog_type -> var_value list -> var_value
  (** Subtracts the following numbers from the first number. All numbers
   *  must be encoded as [String_value].  Returns the result as 
   *  [String_value].
   *)

val mul : dialog_type -> var_value list -> var_value
  (** Multiplies the numbers encoded as [String_value], and returns the product
   * as [String_value].
   *)

val div : dialog_type -> var_value list -> var_value
  (** Divides the first number through the following numbers. All numbers
   *  must be encoded as [String_value].  Returns the result as 
   *  [String_value].
   *)

val assoc : dialog_type -> var_value list -> var_value
  (** Looks the second argument up in the first argument, which must be
   *  an [Alist_value]. The index, i.e. second argument, must be an
   *  [String_value].
   *)

val nth : dialog_type -> var_value list -> var_value
  (** Returns the nth element of the first argument which must be an
   * [Alist_value]. The second argument is the position, a number encoded
   * as [String_value].
   *)

val translate : dialog_type -> var_value list -> var_value
  (** Like ui:translate maps internal values of enumerators to external
   * values. The function takes two arguments:
   * 
   * - [translate [dyn; int]]: The first argument is a dynamic enumerator,
   *   and the second argument is the internal value to translate to the
   *   external value
   * - [translate [type; int]]: The first argument denotes a declared 
   *   enumerator (as a string), and the second argument is the internal 
   *   value to translate to the external value
   *)

val rev_translate : dialog_type -> var_value list -> var_value
  (** Maps external values to internal values:
   * 
   * - [rev_translate [dyn; int]]: The first argument is a dynamic enumerator,
   *   and the second argument is the external value to translate to the
   *   internal value
   * - [translate [type; int]]: The first argument denotes a declared 
   *   enumerator (as a string), and the second argument is the external 
   *   value to translate to the internal value
   *)

val substring : dialog_type -> var_value list -> var_value
  (** Returns a substring of the first argument, a [String_value]. The
   * following forms are accepted:
   *
   * - [substring [s; pos; length]]: The second argument is the position,
   *   and the third argument is the length. The length can be negative.
   * - [substring [s; pos]]: Only the position is passed. Returns the
   *   substring beginning at this position until the end of the string.
   *
   * If the start position or end position of the substring is outside
   * the possible range, only the part of the substring is returned that
   * is inside the possible range.
   *) 

val concat : dialog_type -> var_value list -> var_value
  (** Concatenates all the [String_value] arguments, and returns the
   * result as [String_value].
   *)

val height : dialog_type -> var_value list -> var_value
  (** Returns the height of the [String_value] argument. The height is
   * the number of lines, i.e. the number of LF/CR/CRLF occurrences 
   * plus 1.
   *)

val width : dialog_type -> var_value list -> var_value
  (** Returns the width of the [String_value] argument. The width is
   * the length of the longest line (not counting the line separators).
   *)

val var :  dialog_type -> var_value list -> var_value
  (** Returns the contents of the variable whose name is passed as
   * first argument, a [String_value].
   *)

val dialog : dialog_type -> var_value list -> var_value
  (** Returns the name of the current dialog (no arguments) *)

val page : dialog_type -> var_value list -> var_value
  (** Returns the name of the current page (no arguments) *)

val language : dialog_type -> var_value list -> var_value
  (** Returns the current language, or "" if none selected (no arguments) *)

(* ======================================================================
 * History:
 * 
 * $Log: wd_var_functions.mli,v $
 * Revision 1.3  2003/02/16 01:07:03  stolpmann
 * 	size, substring, width: string positions are measured as
 * the number of characters, not as the number of bytes
 *
 * Revision 1.2  2002/11/03 20:56:56  stolpmann
 * 	New functions: translate, rev_translate
 *
 * Revision 1.1  2002/10/20 19:38:18  stolpmann
 * 	Initial revision
 *
 * 
 *)
