####################################################################################################

  - RINPn ( RINPn ) ReadMe -

  Thank you for downloading RINPn !
  This document is the simple manual for reading at first. Please read this document to the end.

####################################################################################################

RINPn is the simple & compact, programmable, open-source calculator.
This software is implemented in Java(R), so it is available on various desktop OSes.

      Official WebsiteF         https://www.rinearn.com/en-us/rinpn/
      Repository:                https://github.com/RINEARN/rinpn
      Contact to the developerF https://www.rinearn.com/en-us/

Also, more readable guide is bundled as "RINPn_User_Guide.html" in this package.
If a web browser is available on your environment, see also the above guide.

****************************************************************************************************
* Index
****************************************************************************************************

  + About License
  + Please Extract the Downloaded ZIP File Before Using

    - For Microsoft(R) Windows(R)
    - For Linux(R), etc.

  + How to Launch RINPn (GUI Mode)

    - For Microsoft(R) Windows(R)
    - For Linux(R), etc.

  + How to Use After Launching

    - How to Calculate a Expression
    - How to Execute a Script
    - Configure Settings
    - Define Variables and Functions as Script Code (Library Scripts)
    - Implement Embedded Variables/Functions in Java (Plug-in Development)

  + How to Use on the Command-Line (CUI Mode)

  + Built-in Functions and Variables

  + Specs and Caution about Internal Calculation

    - Data are Handled as Binary Floating-Point-Numbers Having Tiny Errors at Tail Digits
    - Precision (Significant Digits) and Roundings

  + Source Code and Repositories
  + Contact Us
  + Credits


****************************************************************************************************
* About License
****************************************************************************************************

  RINPn is an open-source software, released under the MIT License.
  The license document is bundled in "License" folder, 
  so please read it and accept terms of license agreements, before using this software.


  * By the way, at the time you firstly launch this software, 
    you optionally can download Java(R) Runtime Environment(JRE) to "jre" folder, for executing this software.
    The license of that JRE is "GNU GPL version 2 with the Classpath Exception" ( https://openjdk.java.net/legal/gplv2+ce.html ).
    RINPn will be executed on that JRE within the classpath exception.

    You can use that JRE for free, but if you want to redistribute that JRE, 
    you must subject to the terms about redistribution of GNU GPL version 2.


****************************************************************************************************
* Please Extract the Downloaded ZIP File Before Using
****************************************************************************************************

  The downloaded package is compressed by ZIP (extension: .zip) format.
  At first, extract the ZIP file before using, otherwise software will not work correctly.

  * If you opened contents (including this file) of the ZIP file by double-clicking, 
    they are previewed temporary, so the ZIP file is not extracted permanently.


- For Microsoft(R) Windows(R)

  !!! IMPORTANT !!!
  At first, right-click the downloaded ZIP file and choose "Properties" from the menu, 
  and enable "Unblock" checkbox at the right-bottom (in the line of "Security") of 
  the properties-window. 
  Otherwise, when you extract the ZIP file or when you execute the RINPn, 
  security warning messages may pop up and the extraction/execution may fail.

  Then, right-click the ZIP file again, and extract it 
  by selecting "Extract All" and so on from right-clicking menu.


- For Linux(R), etc.

  Right-click the downloaded ZIP file and extract it by selecting the right-clicking menu, 
  or extract on the command-line terminal as follows:

      cd <the_folder_in_which_the_ZIP_file_is>
      unzip -O cp932 rinpn_???.zip       (???: version code)


****************************************************************************************************
* How to Launch RINPn (GUI Mode)
****************************************************************************************************

- For Microsoft(R) Windows(R)

    Double-click the batch file "RINPn.bat" in the extracted folder, 
    and then RINPn will be launched.


  [ About Java(R) Runtime Environment (JRE) ]

    Java(R) Runtime Environment is required for executing this software. 
    If there are no JRE in your environment (or the location of the JRE is not registered 
    in the environment variable "Path"), you optionally can download JRE to "jre" folder, 
    when this software have been launched at the first time.
    In that case, the JRE will be downloaded to "jre" folder of RINPn, 
    from the official website of RINEARN ( https://download.rinearn.com/jre/ ).

    That JRE had generated by "jlink" tool of OpenJDK. 
    Information about the copyright and license of the OpenJDK and so on are as follows:

        Copyright: Oracle Corporation and/or its affiliates
        License:   GNU General Public License version 2 with the Classpath Exception
        Website:   https://openjdk.java.net/

    * See documents in the "jre" folder and README bundled in the JRE for more details.


- For Linux(R), etc.

    Execute the JAR file "RINPn.jar" on the command-line terminal as follows:

        cd <the_folder_in_which_the_JAR_file_is>
        java -jar RinearnProcessorNano.jar

    If you want to specify the memory usage, execute with -Xmx optiopn:

        java -Xmx512m -jar RinearnProcessorNano.jar     (For allocating 512MB)


  [ About Java(R) Runtime Environment (JRE) ]

    For executing this software on Linux(R) and so on, Java(R) Runtime Environment is required separately. 
    If you can use "apt" command on your command-line terminal,  you might install JRE by using apt.

    Firstly, search available packages:

        apt search jre      (or "apt-get" instead of "apt")

    and then install appropriate one, for example:

        sudo apt install default-jre        (or "apt-get" instead of "apt")
    or
        sudo apt install openjdk-?-jre      (?: version numbers)

    Please note that RINPn will not work on JRE with the name ends with "-headles".


****************************************************************************************************
* How to Use After Launching
****************************************************************************************************

- How to Calculate a Expression

    Input the expression you want to calculate in the "INPUT" text field, and press Enter key.
    Then the calculated value will be displayed on the "OUTPUT" text field.

    You can input the whole of the expression such as " 1 + 2 - (3 + 4) / 5 ", 
    and you can control calculation orders of partial expressions by using parentheses ( ).
    You also can use functions in the expression, for example, " ( 1 + 2 * f(3) ) / g(1.23) ".

    Basic operators you should use frequently are:

      + ... Addition
      - ... Subtraction
      * ... Multiplication
      / ... Division
      % ... Reminder


    * See also the latter section "Specs and Caution about Internal Calculation".


- How to Execute a Script

    Instead of an expression, you can execute script code written in a file.

    The script file require to be written in the C-like simple script language "Vnano (VCSSL nano)".
    Write script code by using the general text editor, 
    and save it as a text file of which name ends with the extension ".vnano".
    For the syntax of the Vnano, see: https://github.com/RINEARN/vnano/#language

    For executing the script file, input the file name of it in the "INPUT" text field, 
    and press Enter key.
    If the script file exists in different folder with the RINPn, 
    input the absolute path of the script file to be executed.


- Configure Settings

    "Setting.vnano" is the setting script file. 
    For customization, open that file by the general (your favorite) text editor and edit code. 
    You can customize behaviour, design, and so on by modifying values of parameters.


- Define Variables and Functions as Script Code (Library Scripts)

    Variables and functions define in the library script file "ExampleLibrary.vnano" in "lib" folder
    are available in the expresssion inputted in "INPUT" text-field.
    Open "ExampleLibrary.vnano" by the general text editor and edit code written in there freely.

    As "ExampleLibrary.vnano" is,
    scripts for providing variables/functions are called as "library scripts".
    If you want, you can create new library scripts and can define variables and functions in them. 
    When you have create new library script files, 
    specify them in the text file "VnanoLibraryList.txt" in "lib" folder, for loading them.

    * By the way, under the default settings, all numbers (including integers) 
      in the inputted expression on the calculator window of RINPn 
      will be handled as "float" (64-bit) type.

      This specification is to avoid that the result of division of integers will be evaluated as an integer.
      ( It is expected behaviour in some C-like programming languages including Vnano, 
        but should be unacceptable expected behaviour for the calculator. )

      Therefore, please declare arguments as "float" type, 
      for functions directly called from the expression inputted in the calculator window.

    * In the contrast, numbers described in code in the library script 
      are handled as suitable types for each literals, as the natural behaviour for programmings.
      Variables are also typed based on their declaration.


- Implement Embedded Variables/Functions in Java (Plug-in Development)

    You can implement variables and function in the Java programming language. 
    Note that it requires Java Development Kit (JDK) separately.

    On this software, we refer a Java program to add new embedded variables/function as "plug-in". 
    A simple example of a plug-in is bundled in "plugin" folder as "ExamplePlugin.java".
    As the above example, you can implement variables/functions for this calculator as fields/methods 
    of a Java class. You can use them in expressions of the calculation, or in script files.

    The compilation of plug-ins is:

        (On a command-line terminal)

        cd <plugin_folder>
        javac -classpath ".;../Vnano.jar" -encoding UTF-8 ExamplePlugin.java   (For Microsoft(R) Windows(R))
        javac -classpath ".:../Vnano.jar" -encoding UTF-8 ExamplePlugin.java   (For other Linux(R), etc.)

    When you added a new source file of a plug-in, then compile it in the same way,
    specify them in the text file "VnanoPluginList.txt" in "plugin" folder, for loading them.


****************************************************************************************************
* How to Use on the Command-Line (CUI Mode)
****************************************************************************************************

  In the CUI mode, you can take calculations on the command-line terminal, 
  whithout launching the calculator window.

  To use the CUI mode, register the path of "cmd" folder to the environment variable "PATH" 
  (or "Path") of your OS. For detailed explanation of how to register environment variables, 
  search with the keyword "how to set <name_of_your_os>" on the web.

  Then, wherever the current-directory is, you can launch the RINPn 
  by the following simple command:

        rinpn

  When the "rinpn" command is executed with no arguments as the above, the calculator window 
  which we already used in former sections will be launched (GUI mode).

  In the contrast, if you execute "rinpn" command with passing an expression as an argument, 
  the calculation result will be printed on the command-line terminal, without launching the window:

        rinpn "1 + 2 - (3 + 4) / 5"

  This is the CUI mode. The CUI mode is very simple, but as the same as the GUI mode, all features 
  are available. For example, you can use functions and variables defined in the library script.

  Also, you an execute an script file written in the Vnano as:

        rinpn "Example.vnano"

  If the script file you want to execute exists in a different directory with the current directory,
  specify the relative path of it from the current directory, or the absolute path of it.


****************************************************************************************************
* Built-in Functions and Variables
****************************************************************************************************

  On this calculator software, following functions and variables are available by default.

  * rad( degree )

    The conversion function from degree to radian. Example:

        rad( 180.0 )

  * deg( radian )

    The conversion function from radian to degree. Example:

        deg( 2.0 * PI )

  * sin( x )

    The sine function. The unit of the argument "x" is radian. Example:

        sin( PI / 2.0 )

  * cos( x )

    The cosine function. The unit of the argument "x" is radian. Example:

        cos( 2.0 * PI )

  * tan( x )

    The tangent function. The unit of the argument "x" is radian. Example:

        tan( PI / 4.0 )

  * sqrt( x )

    The square-root function. Example:

        sqrt( 4.0 )

  * ln( x )

    The logarithm function with the base "e" (napier number). Example:

        ln( 10.0 )

  * log10( x )

    The logarithm function with the base "10". Example:

        log10( 1000.0 )

  * pow( x, exponent )

    The function which returns the value of "x" to "exponent"-power. Example:

        pow( 2.0, 3.0 )

  * exp( exponent )

    The function which returns the value of "e" (napier number) to "exponent"-power. Example:

        exp( 1.2 )

  * abs( x )

    The absolute-value function. Example:

        abs( -1.23 )

  * sum( ... )

    The summation function. Example:

        sum( 1.23 ,   4.56 ,   7.89 )

  * mean( ... )

    The mean-value (arithmetic mean) function. Example:

        mean( 1.23 ,   4.56 ,   7.89 )

  * van( ... )

    The variance function ( denominator : n ). Example:

        van( 1.23 ,   4.56 ,   7.89 )

  * van1( ... )

    The variance function ( denominator : n-1 ). Example:

        van1( 1.23 ,   4.56 ,   7.89 )

  * sdn( ... )

    The standard-deviation function ( denominator : n ). Example:

        sdn( 1.23 ,   4.56 ,   7.89 )

  * sdn1( ... )

    The standard-deviation function ( denominator : n-1 ). Example:

        sdn1( 1.23 ,   4.56 ,   7.89 )

  * length( array, dim )

    The function which returns length of the "dim"-th dimension of an "array".

        length( array, 0 )

  * PI

    The constant variable storing the value of the circle ratio . Value:

        3.141592653589793

  In addition, all features of Vnano Standard Plug-ins are available.
  Above functions/variables are also provided by Vnano Standard Plug-ins.
  For the list and details of all features, see the following page:

    https://www.vcssl.org/en-us/vnano/plugin/


****************************************************************************************************
* Specs and Caution about Internal Calculation
****************************************************************************************************

- Data are Handled as Binary Floating-Point-Numbers Having Tiny Errors at Tail Digits

  For the computation of the inputted expression on the calculator window,
  RINPn handles numerical data internally as binary floating-point-numbers.

  Therefore, as in the case of using "float" or "double" types in programmings, 
  you should know that there are some tiny errors at tail digits of such floating-point data. 

  Those errors will caused by various mechanisms, for examples,
  conversions between binary representations and decimal representations of real numbers,
  cutting tails of infinit length of real numbers (e.g. 0.333...) into limited length, and so on.
  As the actual example of the former case, if the following expression:

    0.1 * 3.0

  is computed, the result value will be gotten internally as follows:

    0.30000000000000004 

  This result has very tiny error compared with the true value "0.3".

  Practically, the above internal data will be rounded in 10-digits (depending on settings) 
  just before the data will be outputted on the calculator window. 
  Therefore, in the result value displayed on the calculator window, 
  it might be rare that you encounter explicitly to such tiny errors.

  However, please use this software on understanding that there are those kinds of errors internally.
  It is not recommended to use this software for purposes requires very high-precision 
  for which the above kinds of tiny errors are not permitted.
  Also, we don't recommended to use this software for the purpose of the strict calculation of money.


- Precision (Significant Digits) and Roundings

  The precision of internal data of RINPn is 64-bit, so-called "double-precision".
  The maximum number of significant digits of (the floating-point number) data is about 16 digits.

  Then, there are some tiny errors at tail digits of data, as we mentioned above. 
  To cut out such error-sensitive digits, calculation results will be rounded into about 10-digits 
  before displaying on the calculator window.

  In the setting script file "Setting.nano", you can specify rounding option parameters, 
  for example, how round the calculated values, length (digits) of round results, and so on.


****************************************************************************************************
* Source Code and Repositories
****************************************************************************************************

  RINPn is an open-source software.
  You can access to source code of RINPn on the following public repository:

    https://github.com/RINEARN/rinearn-processor-nano


  Incidentally, RINPn is using the script engine of the "Vnano" 
  for internal computations. 
  This script engine is open-source too, so you can use it on your software developments. 
  It might be usefull for evaluating values of expressions inputted by users, 
  reading setting values from script file, as RINPn is doing.
  You can access to source code of the Vnano script engine on the following public repository:

    https://github.com/RINEARN/vnano


****************************************************************************************************
* Contact Us
****************************************************************************************************

  Please feel free to contact us from the following website: 

      https://www.rinearn.com/en-us/


****************************************************************************************************
* Credits
****************************************************************************************************

  [1] Oracle and Java are registered trademarks of Oracle and/or its affiliates.
  [2] Microsoft Windows is either a registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
  [3] Linux is a trademark of linus torvalds in the United States and/or other countries.

  Other names may be either a registered trademarks or trademarks of their respective owners.
