Implement support for writing UI Automation Remote Operations natively in NVDA using Python

source/UIAHandler/_remoteOps/instructions/__init__.py

@@ -0,0 +1,111 @@
+# A part of NonVisual Desktop Access (NVDA)
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+# Copyright (C) 2023-2024 NV Access Limited
+
+"""
+This package contains all the instructions that can be executed by the remote ops framework.
+Each instruction contains the appropriate op code and parameter types.
+Most instructions also contain a `localExecute` method,
+which provides an implementation of the instruction that can be executed locally.
+"""
+
+
+# Import all instructions so that they can be accessed as attributes of this module.
+# flake8: noqa: F401
+
+
+from ..builder import InstructionBase
+from .arithmetic import (
+	BinaryAdd,
+	BinarySubtract,
+	BinaryMultiply,
+	BinaryDivide,
+	InplaceAdd,
+	InplaceSubtract,
+	InplaceMultiply,
+	InplaceDivide,
+)
+from .array import (
+	NewArray,
+	IsArray,
+	ArrayAppend,
+	ArrayGetAt,
+	ArrayRemoveAt,
+	ArraySetAt,
+	ArraySize,
+)
+from .bool import (
+	NewBool,
+	IsBool,
+	BoolNot,
+	BoolAnd,
+	BoolOr,
+)
+from .controlFlow import (
+	Halt,
+	Fork,
+	ForkIfFalse,
+	NewLoopBlock,
+	EndLoopBlock,
+	NewTryBlock,
+	EndTryBlock,
+	BreakLoop,
+	ContinueLoop,
+)
+from .element import (
+	IsElement,
+	ElementGetPropertyValue,
+	ElementNavigate,
+)
+from .extension import (
+	IsExtensionSupported,
+	CallExtension,
+)
+from .float import (
+	NewFloat,
+	IsFloat,
+)
+from .general import (
+	Set,
+	Compare,
+	Stringify,
+)
+from .guid import (
+	NewGuid,
+	IsGuid,
+)
+from .int import (
+	NewInt,
+	IsInt,
+	NewUint,
+	IsUint,
+)
+from .null import (
+	NewNull,
+	IsNull,
+)
+from .status import (
+	SetOperationStatus,
+	GetOperationStatus,
+)
+from .string import (
+	NewString,
+	IsString,
+	StringConcat,
+)
+from .textRange import (
+	TextRangeGetText,
+	TextRangeMove,
+	TextRangeMoveEndpointByUnit,
+	TextRangeCompare,
+	TextRangeClone,
+	TextRangeFindAttribute,
+	TextRangeFindText,
+	TextRangeGetAttributeValue,
+	TextRangeGetBoundingRectangles,
+	TextRangeGetEnclosingElement,
+	TextRangeExpandToEnclosingUnit,
+	TextRangeMoveEndpointByRange,
+	TextRangeCompareEndpoints,
+)

source/UIAHandler/_remoteOps/instructions/_base.py

@@ -0,0 +1,17 @@
+# A part of NonVisual Desktop Access (NVDA)
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+# Copyright (C) 2023-2024 NV Access Limited
+
+
+from __future__ import annotations
+from ..builder import (
+	InstructionBase,
+)
+
+
+class _TypedInstruction(InstructionBase):
+
+	@property
+	def params(self):
+		return vars(self)

source/UIAHandler/_remoteOps/instructions/arithmetic.py

@@ -0,0 +1,110 @@
+# A part of NonVisual Desktop Access (NVDA)
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+# Copyright (C) 2023-2024 NV Access Limited
+
+"""
+This module contains the instructions that perform arithmetic operations,
+such as addition, subtraction, multiplication, and division.
+Both binary and in-place operations are supported.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+from .. import lowLevel
+from .. import builder
+from ._base import _TypedInstruction
+
+
+@dataclass
+class BinaryAdd(_TypedInstruction):
+	opCode = lowLevel.InstructionType.BinaryAdd
+	result: builder.Operand
+	left: builder.Operand
+	right: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.result.operandId] = registers[self.left.operandId] + registers[self.right.operandId]
+
+
+@dataclass
+class BinarySubtract(_TypedInstruction):
+	opCode = lowLevel.InstructionType.BinarySubtract
+	result: builder.Operand
+	left: builder.Operand
+	right: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.result.operandId] = registers[self.left.operandId] - registers[self.right.operandId]
+
+
+@dataclass
+class BinaryMultiply(_TypedInstruction):
+	opCode = lowLevel.InstructionType.BinaryMultiply
+	result: builder.Operand
+	left: builder.Operand
+	right: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.result.operandId] = registers[self.left.operandId] * registers[self.right.operandId]
+
+
+@dataclass
+class BinaryDivide(_TypedInstruction):
+	opCode = lowLevel.InstructionType.BinaryDivide
+	result: builder.Operand
+	left: builder.Operand
+	right: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		left = registers[self.left.operandId]
+		right = registers[self.right.operandId]
+		if isinstance(left, int) and isinstance(right, int):
+			result = left // right
+		else:
+			result = left / right
+		registers[self.result.operandId] = result
+
+
+@dataclass
+class InplaceAdd(_TypedInstruction):
+	opCode = lowLevel.InstructionType.Add
+	target: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.target.operandId] += registers[self.value.operandId]
+
+
+@dataclass
+class InplaceSubtract(_TypedInstruction):
+	opCode = lowLevel.InstructionType.Subtract
+	target: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.target.operandId] -= registers[self.value.operandId]
+
+
+@dataclass
+class InplaceMultiply(_TypedInstruction):
+	opCode = lowLevel.InstructionType.Multiply
+	target: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.target.operandId] *= registers[self.value.operandId]
+
+
+@dataclass
+class InplaceDivide(_TypedInstruction):
+	opCode = lowLevel.InstructionType.Divide
+	target: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		target = registers[self.target.operandId]
+		value = registers[self.value.operandId]
+		if isinstance(target, int) and isinstance(value, int):
+			registers[self.target.operandId] //= value
+		else:
+			registers[self.target.operandId] /= value

source/UIAHandler/_remoteOps/instructions/array.py

@@ -0,0 +1,93 @@
+# A part of NonVisual Desktop Access (NVDA)
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+# Copyright (C) 2023-2024 NV Access Limited
+
+"""
+This module contains the instructions that operate on arrays.
+Including to create new arrays, append, get, set, and remove elements from arrays,
+and check if an object is an array.
+"""
+
+from __future__ import annotations
+from typing import cast
+from dataclasses import dataclass
+from .. import lowLevel
+from .. import builder
+from ._base import _TypedInstruction
+
+
+@dataclass
+class NewArray(_TypedInstruction):
+	opCode = lowLevel.InstructionType.NewArray
+	result: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.result.operandId] = []
+
+
+@dataclass
+class IsArray(_TypedInstruction):
+	opCode = lowLevel.InstructionType.IsArray
+	result: builder.Operand
+	target: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		registers[self.result.operandId] = isinstance(registers[self.target.operandId], list)
+
+
+@dataclass
+class ArrayAppend(_TypedInstruction):
+	opCode = lowLevel.InstructionType.RemoteArrayAppend
+	target: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		array = cast(list, registers[self.target.operandId])
+		array.append(registers[self.value.operandId])
+
+
+@dataclass
+class ArrayGetAt(_TypedInstruction):
+	opCode = lowLevel.InstructionType.RemoteArrayGetAt
+	result: builder.Operand
+	target: builder.Operand
+	index: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		array = cast(list, registers[self.target.operandId])
+		registers[self.result.operandId] = array[cast(int, registers[self.index.operandId])]
+
+
+@dataclass
+class ArrayRemoveAt(_TypedInstruction):
+	opCode = lowLevel.InstructionType.RemoteArrayRemoveAt
+	target: builder.Operand
+	index: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		array = cast(list, registers[self.target.operandId])
+		del array[cast(int, registers[self.index.operandId])]
+
+
+@dataclass
+class ArraySetAt(_TypedInstruction):
+	opCode = lowLevel.InstructionType.RemoteArraySetAt
+	target: builder.Operand
+	index: builder.Operand
+	value: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		array = cast(list, registers[self.target.operandId])
+		array[cast(int, registers[self.index.operandId])] = registers[self.value.operandId]
+
+
+@dataclass
+class ArraySize(_TypedInstruction):
+	opCode = lowLevel.InstructionType.RemoteArraySize
+	result: builder.Operand
+	target: builder.Operand
+
+	def localExecute(self, registers: dict[lowLevel.OperandId, object]):
+		array = cast(list, registers[self.target.operandId])
+		registers[self.result.operandId] = len(array)