=head1 NAME

SPVM::Document::NativeAPI - SPVM Native API

=head1 What is Native API

Native API is C level functions to manipulate data of SPVM in L<NativeAPI|SPVM::Document::NativeAPI>.

If you need more performance or bind C/C++ functions, you can use L<NativeAPI|SPVM::Document::NativeAPI> and Native API.

=head1 Tutorial

=head2 Runtime Compile Native Function

If you use the feature Runtime Compile Native Function, you can write program using C language in runtime.
This is similar with L<NativeAPI::C>, but L<SPVM> implement this feature by default.
  
  # TestCase/NativeAPI.spvm
  package TestCase::NativeAPI {
    native sub sum : int ($num1 : int, $num2 : int);
  }
  
  // TestCase/NativeAPI.native/NativeAPI.c
  #include <spvm_native.h>
  
  int32_t SPNATIVE__TestCase__NativeAPI__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
    
    int32_t total = stack[0].ival + stack[1].ival;
    
    // Return value is set to stack[0]
    stack[0].ival = total;
    
    // If function success, return SPVM_SUCCESS
    return SPVM_SUCCESS;
  }

At first, you specify C<native> descripter at SPVM subroutine.

  package TestCase::NativeAPI {
    # native descripter
    native sub sum : int ($num1 : int, $num2 : int);
  }

Next, you create "TestCase/NativeAPI/NativeAPI.c" file
  
  TestCase/NativeAPI.spvm
  TestCase/NativeAPI.native/NativeAPI.c

Next, you write C language. You include C<spvm_native.h>.

  #include <spvm_native.h>

C Function name start with C<SPNATIVE__>.
C Function name must be replace C<:> with <_>.
If SPVM subroutine belong to C<TestCase::NativeAPI> package and subroutine name is Csum>,
Declaration is the following.

  int32_t SPNATIVE__TestCase__NativeAPI__sum(SPVM_ENV* env, SPVM_VALUE* stack) {

    int32_t total = stack[0].ival + stack[1].ival;
    
    // Return value is set to stack[0]
    stack[0].ival = total;
    
    // If function success, return SPVM_SUCCESS
    return SPVM_SUCCESS;
  }

First argument is C<env>. This is the pointer to C<SPVM_ENV>. Second argument is C<stack>. stack constains arguments.

SPVM_VALUE is union of C language. If you want to get int value, you do the followng.

  stack[0].ival

You can get all type of value by the following member.

  stack[0].bval
  stack[0].sval
  stack[0].ival
  stack[0].lval
  stack[0].fval
  stack[0].dval
  stack[0].oval

Type of return value is corresponding the folloing type.

  [SPVM]              [C]
  byte                int8_t
  short               int16_t
  int                 int32_t
  long                int64_t
  float               float
  double              double
  [Object value]      void*

=head1 NAME

SPVM::Guides::LanguageSpecification - The SPVM 1.0 Language Specification

=head1 DESCRIPTION

The SPVM 1.0 Language Specification is described in this document.
SPVM is in beta testing for the 1.0 release.
Language specifications are subject to change without warning.

SPVM Language is designed to be used from Perl. Perl can call SPVM subroutines.

SPVM Language provides fast array operation and fast numeric calculation.

SPVM subroutines is executed by the SPVM Runtime. its can be converted to shared libraries or DLL.

SPVM Language can be converted to machine codes, and you can execute them as a single executable.

Executables contain not only Unix/Linux/macOS/ios executable, but also Windows Native Executable, 

=head1 C99 compliant

=head2 C99-compliant compiler and runtime

The source code for the SPVM compiler and SPVM runtime is written in C and conforms to C99.

Note that this does not mean that the user cannot call C versions other than C99 (C11, GNU extensions, etc.) or code written in C ++ from SPVM. This means that the SPVM compiler and runtime must be C99 compliant.

=head2 Correspondence of type with C99

The SPVM type exactly matches the following C99 types:

=begin html

      <table>
        <tr>
          <th>
            <b> SPVM type </ b>
          </ th>
          <th>
            <b> C99 type </ b>
          </ th>
          <th>
            <b> Description </ b>
          </ th>
        </ tr>
        <tr>
          <td>
            <b> byte </ b>
          </ td>
          <td>
            int8_t
          </ td>
          <td>
            SPVM <a href="#language-type-byte"> byte type </a> matches C99 int8_t type.
          </ td>
        </ tr>
        <tr>
          <td>
            <b> short </ b>
          </ td>
          <td>
            int16_t
          </ td>
          <td>
            SPVM <a href="#language-type-short"> short type</a> matches the C99 int16_t type.
          </ td>
        </ tr>
        <tr>
          <td>
            <b> int </ b>
          </ td>
          <td>
            int32_t
          </ td>
          <td>
            SPVM <a href="#language-type-int"> int type </a> matches the C99 int32_t type.
          </ td>
        </ tr>
        <tr>
          <td>
            <b> long </ b>
          </ td>
          <td>
            int64_t
          </ td>
          <td>
            SPVM <a href="#language-type-long"> long type </a> matches C99 int64_t type.
          </ td>
        </ tr>

<tr>
          <td>
            <b> float </ b>
          </ td>
          <td>
            float
          </ td>
          <td>
            SPVM <a href="#language-type-float"> float type </a> matches the C99 float type.
          </ td>
        <tr>
          <td>
            <b> double </ b>
          </ td>
          <td>
            double
          </ td>
          <td>
            SPVM <a href="#language-type-double"> double type</a> matches C99 double.
          </ td>
        </ tr>
        <tr>
          <td>
            <b> Object type </ b>
          </ td>
          <td>
            void*
          </ td>
          <td>
            SPVM <a href="#language-type-object"> object type </a> matches the C99 void* type.
          </ td>
        </ tr>        
        <tr>
          <td>
            <b> Multiple numeric type </ b>
          </ td>
          <td>
            Numeric array type that matches tye type and the length of the fields of SPVM multiple numeric type
          </ td>
          <td>
            <p>
              For example, if <a href="#language-type-multi-numeric"> the multiple numeric type is</a>
            </ p>
            <p>
              <b>package Point_2i: mulnum_t {has x: int; has y: int;}</b>
            </ p>
            <p>
              It matches the type declared in C99
            </ p>
            <p>
              <b>int32_t var[2];</b>
            </p>
          </ td>
        </ tr>
      </table>

=end html

=head1 Parsing

=head1 comment

=head1 POD

=head1 package

=head1 module

=head1 Permission

=head1 Package variables

=head1 field

=head1 subroutine

=head1 Enumeration

=head1 BEGIN block

=head1 Lexical variable

=head1 block

=head1 scope

=head1 Array

=head1 value

=head1 An array of values

=head1 reference

=head1 warning

=head1 Exception handling

=head1 Callback

=head1 Week reference

=head1 formula

=head1 literal

=head1 Fat Comma

=head1 String

=head1 Undefined value

=head1 operator

=head1 Operator precedence

=head1 Sentence

=head1 Type

=head1 Type inference

=head1 Type conversion

=head1 Thread safe

=head1 Automatically loaded modules

=head1 Restriction