### Refactor Key PMC handling in Parrot-Linear-Algebra

**completed by**: Fernando Brito

**mentors**: whiteknight

**Task Description:** Parrot-Linear-Algebra(PLA) is a linear-algebra package for the Parrot Virtual Machine. PLA adds matrix/vector data types and operations for Parrot's users.

A Key PMC is a linked-list structure which contains indices. A Key PMC can be used to make lookups in multi-dimensional structures by doing linear lookups recursively. Arity is the number of elements in a Key. If we have an array of arrays, we can use n Arity 2 Key (a Key with two elements) to find a single element in it. We pop the first index off the key, and use it to look up the inner array. Then we pass the new Arity 1 key to the inner array to perform the second lookup.

PLA matrix types are flat structures in memory, so lookups cannot be made recursively like it can for array-in-array structures. PLA matrix types require that a Key PMC have arity 1 (to lookup in the matrix like an array) or arity 2 *exactly*. No other arities make sense.

PLA uses the GET_KEY_INDICES_ROWMAJOR and GET_KEY_INDICES_COLMAJOR macros to read values out of a Key. However, this macro does no error checking, and does not accept any other types of inputs (like an integer array) that may also be useful. This needs to be fixed.

**Steps to Complete**:

- Create a fork of Whiteknight/parrot-linear-algebra on Github
- In the file src/lib/matrix_common.c, create a new function "pmckey_to_coords" to convert a PMC into two INTVAL coordinates. You can use the intkey_to_coords function as a template.
- If the PMC is a Key (pmc->vtable->base_type == enum_class_Key) you will need to figure out how many elements it has, and throw an error if it isn't 1 or 2. Get those values out of the key.
- If the PMC is an array (VTABLE_does(interp, pmc, CONST_STRING(interp, "array"))) make sure it has one or two elements. Get those values out of the array
- If we have 1 element, we can duplicate the logic from intkey_to_coords, or call that function directly to avoid duplicating logic
- If we have 2 elements, we can return them directly

- Update the macros GET_KEY_INDICES_ROWMAJOR and GET_KEY_INDICES_COLMAJOR to call your new function
- Add at 3 tests each to t/pmc/complexmatrix2d.t, t/pmc/nummatrix2d.t and t/pmc/pmcmatrix2d.t. These new tests should test:
- That a Key with more than 2 elements throws an exception
- That an array of 2 integers can be used to look up an item in the matrix
- That an empty array (0 elements) throws an exception

- Build PLA and run all tests to verify
- Open a pull request on github to have your work merged in.

**Links**: matrix_common.c, **parrot-linear-algebra**