- JavaDoc

# Jep Java

- Introduction
- Basic Usage
- Variables
- Data types
- Operators
- Functions
- Custom Functions
- BigDecimal
- Modules
- Printing
- FAQ
- Migration
- Version History

# Advanced Features

- Manipulating Expressions
- Components
- Configurable Parser
- Serialization
- Threads
- Localization
- Grammar
- Other advanced features
- Use of Design Patterns in Jep

# Localization

In Jep 3.5 all error messages are externalized using the standard Java Internationalization mechanism. See Java Trail: Internationalization for of an overview.

The default messages are contained in the `com/singularsys/jep/messages.properties` file which can be customized. A copy of this file can be found here: messages.properties.

### Custom messages file

A localized version of the messages file can be specified for a given language and country A typical copy of the properties file might be

    FunctionRequiresNArgumentsFoundN=Fonction «%s» nécessite %d arguments, a trouvé %d.
    functions.IllegalParameterException.UnknownFunction=Fonction inconnue
    functions.IllegalParameterException.IllegalArgument=: argument illégal:
    functions.IllegalParameterException.IllegalArguments=: arguments illégal:
    functions.IllegalParameterException.Comma=,
    functions.IllegalParameterException.Expected=\ attendus %s
    functions.IllegalParameterException.ExpectedMsg=\ attendus %s
    functions.IllegalParameterException.ActualValueClass=\ %s[%s]
    functions.IllegalParameterException.ArgumentNumber=,\ numéro %d argument.

The first line gives the message printed when a function is specified with the wrong number of arguments, say `sin(1,2)`. This message is a format string used by `String.format(spec,args...)`. The second example is a more complex message with multiple parts used when an illegal argument is passed to a function or operator. Not all messages needs to be supplied, some are extremely rare.

For the system to find the file it must be in the class path in the `com/singularsys/jep` directory and named `messages_(language)_(Country).properties` for example `com/singularsys/jep/messages_fr_CA.properties` would specify the messages for French (fr) Canadian (CA) locale.

### Setting the default Locale

The default locale is normally set by the system. This can be overridden by specifying the `user.language` and `user.country` properties on the command line

    java -Duser.language=fr -Duser.country=CA com.singularsys.jepexamples.consoles.Console

on unix machines it may be possible to set the default locale by setting the environment variable, `LANG`, `LC_ALL` or `LC_MESSAGES`.

      bash % export LC_ALL=de_DE

The default locale can also be set within java using

      Locale.setDefault(Locale.GERMANY);

this should be called before any Jep code is loaded.

### Testing messages

The `com.singularsys.jeptests.system.MessagesTest` class is a JUnit test class which tests and displays all messages printed by the system. You can use this class to check the results of any custom localization messages.

### Standard Error reporting methods

The PostfixMathCommand the base class for custom functions provides a number of methods for checking the types of arguments. For example `double asDouble(int position, Object value)` checks that the `value` can be converted to a double. If not a standard error message is generated using the `position` argument and an IllegalParameterException thrown with this message. For example this method is used in the Signum if it is supplied with an illegal argument, say `signum("abc")` then the message

    signum: illegal argument: abc[String] expected Number, argument number 0.

is generated using the `functions.IllegalParameterException.IllegalArgument`, `functions.IllegalParameterException.ActualValueClass`, `functions.IllegalParameterException.Expected` and `functions.IllegalParameterException.ArgumentNumber` messages. Other conversion methods include `asString(pos,str)`, `asInt(pos,val)`, `asLong(pos,val)`, `asBool(pos,val)`, and `asStrictInt(pos,val)`. The final method not only checks if the number can be converted to an integer it also checks that no rounding occurs.

The IllegalParameterException class offers a number of different constructors for easy generation of standard error messages. If you want your own error message use the parent class EvaluationException.

### Function names and descriptions

The StandardFunctionTable StringFunctionSet and similar FunctionTable and FunctionSet through the system, allow names of functions, and short one line descriptions to be set using the properties file. Function descriptions are used in the help messages of the Console applications.

For example the name of the `arccos` function and its description are specified using the following lines in the properties file.

    StandardFunctionTable.arccos=acos
    com.singularsys.jep.functions.ArcCosine.description=arc cosine

Descriptions can be set based on the qualified class name; defined for a specific instance by calling PostfixMathCommand.setDescription(String) or for special cases by overriding the PostfixMathCommand.getDescription() This of often used when the same PostfixMathCommand subclass is used to implement multiple functions. For example the `LazyLogical` class implements both the AND `&&` and OR `||` operators have thier descriptions set using

    com.singularsys.jep.functions.LazyLogical.AND.description=logical and
    com.singularsys.jep.functions.LazyLogical.OR.description=logical or

The properties file can also be used to supress the definition of a function by setting its property to an entry beginning with a `!` character. For example to skip the definition of the `rand` use

    StandardFunctionTable.rand=! not implemented

Missing properties also cause the function to be skipped.

By default only the `com.singularsys.jep.messages` properties bundles is queried for function names and descriptions. To extend the search path use:

    {
    JepMessages.addBundle("com.singularsys.extensions.messages");
    }

at the start of any class.