native methods

Author: mattcce

src/ec-evaluator/__tests__/natives.test.ts

@@ -0,0 +1,67 @@
+import { natives } from '../natives'
+import {
+  //   ControlStub,
+  //   StashStub,
+  createContextStub
+  //   getControlItemStr,
+  //   getStashItemStr
+} from './__utils__/utils'
+import { parse } from '../../ast/parser'
+import { evaluate } from '../interpreter'
+
+describe('native functions', () => {
+  it('should invoke external native function', () => {
+    const mockForeignFn = jest.fn()
+
+    natives['testNative(): void'] = mockForeignFn
+
+    const programStr = `
+    class C {
+        public native void testNative();
+
+        public static void main(String[] args) {
+            C c = new C();
+            c.testNative();
+        }
+    }`
+
+    const compilationUnit = parse(programStr)
+    expect(compilationUnit).toBeTruthy()
+
+    const context = createContextStub()
+    context.control.push(compilationUnit!)
+
+    evaluate(context)
+
+    expect(mockForeignFn.mock.calls).toHaveLength(1)
+  })
+
+  it('should invoke external native function with correct environment', () => {
+    const foreignFn = jest.fn(({ environment }) => {
+      const s = environment.getVariable('s').value.literalType.value
+      expect(s).toBe('"Test"')
+    })
+
+    natives['testNative(String s): void'] = foreignFn
+
+    const programStr = `
+    class C {
+        public native void testNative(String s);
+
+        public static void main(String[] args) {
+            C c = new C();
+            c.testNative("Test");
+        }
+    }`
+
+    const compilationUnit = parse(programStr)
+    expect(compilationUnit).toBeTruthy()
+
+    const context = createContextStub()
+    context.control.push(compilationUnit!)
+
+    evaluate(context)
+
+    expect(foreignFn.mock.calls).toHaveLength(1)
+  })
+})

src/ec-evaluator/errors.ts

@@ -160,3 +160,13 @@ export class NoMainMtdError extends RuntimeError {
     return `public static void main(String[] args) is not defined in any class.`
   }
 }
+
+export class UndefinedNativeMethod extends RuntimeError {
+  constructor(private descriptor: string) {
+    super()
+  }
+
+  public explain() {
+    return `Native function ${this.descriptor} has no defined implementation.`
+  }
+}

src/ec-evaluator/interpreter.ts

@@ -87,12 +87,15 @@ import {
   searchMainMtdClass,
   prependExpConInvIfNeeded,
   isStatic,
+  isNative,
   resOverload,
   resOverride,
   resConOverload,
   isNull,
-  makeNonLocalVarNonParamSimpleNameQualified
+  makeNonLocalVarNonParamSimpleNameQualified,
+  getFullyQualifiedDescriptor
 } from './utils'
+import { natives } from './natives'
 
 type CmdEvaluator = (
   command: ControlItem,
@@ -136,7 +139,7 @@ export const evaluate = (
   return stash.peek()
 }
 
-const cmdEvaluators: { [type: string]: CmdEvaluator } = {
+export const cmdEvaluators: { [type: string]: CmdEvaluator } = {
   CompilationUnit: (
     command: CompilationUnit,
     _environment: Environment,
@@ -501,6 +504,28 @@ const cmdEvaluators: { [type: string]: CmdEvaluator } = {
       environment.defineVariable(params[i].identifier, params[i].unannType, args[i])
     }
 
+    // Native function escape hatch
+    if (closure.mtdOrCon.kind === 'MethodDeclaration' && isNative(closure.mtdOrCon)) {
+      const nativeFn = natives[getFullyQualifiedDescriptor(closure.mtdOrCon)]
+
+      if (!nativeFn) {
+        throw new errors.UndefinedNativeMethod(nativeFn)
+      }
+
+      // call foreign fn
+      nativeFn({ control, stash, environment })
+
+      // only because resetInstr demands one, never actually used
+      const superfluousReturnStatement: ReturnStatement = {
+        kind: 'ReturnStatement',
+        exp: { kind: 'Void' }
+      }
+
+      // handle return from native fn
+      control.push(instr.resetInstr(superfluousReturnStatement))
+      return
+    }
+
     // Push method/constructor body.
     const body =
       closure.mtdOrCon.kind === 'MethodDeclaration'

src/ec-evaluator/natives.ts

@@ -0,0 +1,29 @@
+import { Control, Environment, Stash } from './components'
+
+/*
+    Native function escape hatch.
+
+    Used for implementing native methods. Allows for purely arbitrary modification to the control, stash, and environment via an external handler function.
+
+    All native functions are expected to respect Java method call preconditions and postconditions, with the exception of returning. When a native function is called, it can expect the following.
+
+    Preconditions: environment has been initialised for the current function call.
+
+    Postconditions: returned result must be pushed onto the top of the stash.
+
+    The current implementation automatically injects a return instruction after the external handler function call ends.
+*/
+
+export type NativeFunction = ({
+  control,
+  stash,
+  environment
+}: {
+  control: Control
+  stash: Stash
+  environment: Environment
+}) => void
+
+export const natives: {
+  [descriptor: string]: NativeFunction
+} = {}

src/ec-evaluator/nodeCreator.ts

@@ -138,5 +138,41 @@ export const objClassDeclNode = (): ClassDeclaration => ({
   kind: 'NormalClassDeclaration',
   classModifier: [],
   typeIdentifier: OBJECT_CLASS,
-  classBody: []
+  classBody: [
+    {
+      kind: 'FieldDeclaration',
+      fieldModifier: ['private'],
+      fieldType: 'int',
+      variableDeclaratorList: [
+        {
+          kind: 'VariableDeclarator',
+          variableDeclaratorId: 'hash',
+          variableInitializer: {
+            kind: 'Literal',
+            literalType: {
+              kind: 'DecimalIntegerLiteral',
+              value: String(Math.floor(Math.random() * Math.pow(2, 32)))
+            }
+          }
+        }
+      ]
+    },
+    {
+      kind: 'MethodDeclaration',
+      methodModifier: ['public'],
+      methodHeader: { result: 'int', identifier: 'hashCode', formalParameterList: [] },
+      methodBody: {
+        kind: 'Block',
+        blockStatements: [
+          {
+            kind: 'ReturnStatement',
+            exp: {
+              kind: 'ExpressionName',
+              name: 'this.hash'
+            }
+          }
+        ]
+      }
+    }
+  ]
 })

src/ec-evaluator/utils.ts

@@ -183,6 +183,11 @@ export const getDescriptor = (mtdOrCon: MethodDeclaration | ConstructorDeclarati
     : `${mtdOrCon.constructorDeclarator.identifier}(${mtdOrCon.constructorDeclarator.formalParameterList.map(p => p.unannType).join(',')})`
 }
 
+// for native methods (uses new proposed format) with parameter names
+// because native functions must retrieve variables from the environment by identifier, this descriptor type also includes parameter names for convenience
+export const getFullyQualifiedDescriptor = (mtd: MethodDeclaration): string =>
+  `${mtd.methodHeader.identifier}(${mtd.methodHeader.formalParameterList.map(p => `${p.unannType} ${p.identifier}`).join(',')}): ${mtd.methodHeader.result}`
+
 export const isQualified = (name: string) => {
   return name.includes('.')
 }
@@ -230,6 +235,10 @@ export const isInstance = (fieldOrMtd: FieldDeclaration | MethodDeclaration): bo
   return !isStatic(fieldOrMtd)
 }
 
+export const isNative = (mtd: MethodDeclaration): boolean => {
+  return mtd.methodModifier.includes('native')
+}
+
 const convertFieldDeclToExpStmtAssmt = (fd: FieldDeclaration): ExpressionStatement => {
   const left = `this.${fd.variableDeclaratorList[0].variableDeclaratorId}`
   // Fields are always initialized to default value if initializer is absent.