refactor(core): remove unused context APIs 🌱

core/include/keyman/keyman_core_api_context.h

@@ -1,14 +1,7 @@
 /*
  * Keyman is copyright (C) SIL International. MIT License.
  *
- * Keyman Keyboard Processor API - Debugger Interfaces
- *
- * The debugger interfaces are still very dependent on .kmx
- * objects.
- *
- * Note: this file is subject to change; the debugger
- *       interfaces are not stable across versions.
- *
+ * Keyman Keyboard Processor API - Context Interfaces
  */
 
 #pragma once
@@ -18,12 +11,6 @@
 #include <keyman/keyman_core_api_bits.h>
 #include <keyman/keyman_core_api_vkeys.h>
 
-// Currently, the Core unit tests use private context APIs defined in
-// keyman_core_api_context.h, which are unused by other consumers. We are
-// hoping to remove these entirely in the future, so we restrict access
-// by default with this macro. Keyman Core internally uses these functions
-// #define _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
 #if defined(__cplusplus)
 extern "C"
 {
@@ -104,7 +91,8 @@ km_core_state_get_intermediate_context(km_core_state *state, km_core_context_ite
 ### `km_core_context_items_dispose`
 ##### Description:
 Free the allocated memory belonging to a `km_core_context_item` array previously
-returned by `km_core_context_items_from_utf16` or `km_core_context_get`
+returned by `km_core_state_get_intermediate_context` (internally, also
+`context_items_from_utf16` and `context_get`)
 ##### Parameters:
 - __context_items__: A pointer to the start of the `km_core_context_item` array
     to be disposed of.
@@ -137,181 +125,6 @@ KMN_API
 km_core_context *
 km_core_state_app_context(km_core_state const *state);
 
-/*
-```
-### `km_core_context_items_from_utf16`
-##### Description:
-Convert a UTF16 encoded Unicode string into an array of `km_core_context_item`
-structures. Allocates memory as needed.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_NO_MEM`: In the event not enough memory can be allocated for the
-  output buffer.
-- `KM_CORE_STATUS_INVALID_UTF`: In the event the UTF16 string cannot be decoded
-  because it contains unpaired surrogate codeunits.
-##### Parameters:
-- __text__: a pointer to a null terminated array of utf16 encoded data.
-- __out_ptr__: a pointer to the result variable:
-    A pointer to the start of the `km_core_context_item` array containing the
-    representation of the input string.
-    Terminated with a type of `KM_CORE_CT_END`. Must be disposed of with
-    `km_core_context_items_dispose`.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_items_from_utf16(km_core_cp const *text,
-                                km_core_context_item **out_ptr);
-
-#endif
-
-/*
-```
-### `km_core_context_items_from_utf8`
-##### Description:
-Convert an UTF8 encoded Unicode string into an array of `km_core_context_item`
-structures. Allocates memory as needed.
-##### Status:
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_NO_MEM`: In the event it cannot allocate enough memory for the
-  output buffer.
-- `KM_CORE_STATUS_INVALID_UTF`: In the event the UTF8 string cannot be
-decoded.
-##### Parameters:
-- __text__: a pointer to a null terminated array of utf8 encoded data.
-- __out_ptr__: a pointer to the result variable:
-    A pointer to the  start of the `km_core_context_item` array containing the
-    representation of the input string.
-    Terminated with a type of `KM_CORE_CT_END`.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_items_from_utf8(char const *text,
-                                km_core_context_item **out_ptr);
-
-#endif
-
-/*
-```
-### `km_core_context_items_to_utf16`
-##### Description:
-Convert a context item array into a UTF-16 encoded string placing it into
-the supplied buffer of specified size, and return the number of code units
-actually used in the conversion. If null is passed as the buffer the
-number of codeunits required is returned. Any markers in the context will
-not be included in the output buffer.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_INSUFFICENT_BUFFER`: If the buffer is not large enough.
-  `buf_size` will contain the space required. The contents of the buffer are
-  undefined.
-##### Parameters:
-- __context_items__: A pointer to the start of an array `km_core_context_item`.
-    Must be terminated with a type of `KM_CORE_CT_END`.
-- __buf__: A pointer to the buffer to place the UTF-16 string into.
-    May be null to request size calculation.
-- __buf_size__: a pointer to the result variable:
-    The size of the supplied buffer in codeunits if `buf` is given.
-    On return will be the size required if `buf` is null.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_items_to_utf16(km_core_context_item const *item,
-                              km_core_cp *buf,
-                              size_t *buf_size);
-
-#endif
-
-/*
-```
-### `km_core_context_items_to_utf8`
-##### Description:
-Convert a context item array into a UTF-8 encoded string placing it into
-the supplied buffer of specified size, and return the number of code units
-actually used in the conversion. If null is passed as the buffer the
-number of codeunits required is returned. Any markers in the context will
-not be included in the output buffer.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_INSUFFICENT_BUFFER`: If the buffer is not large enough.
-  `buf_size` will contain the space required. The contents of the buffer are
-  undefined.
-##### Parameters:
-- __context_items__: A pointer to the start of an array `km_core_context_item`.
-    Must be terminated with a type of `KM_CORE_CT_END`.
-- __buf__: A pointer to the buffer to place the UTF-8 string into.
-    May be null to request size calculation.
-- __buf_size__: a pointer to the result variable:
-    The size of the supplied buffer in codeunits if `buf` is given.
-    On return will be the size required if `buf` is null.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_items_to_utf8(km_core_context_item const *item,
-                              char *buf,
-                              size_t *buf_size);
-
-#endif
-
-/*
-```
-### `km_core_context_items_to_utf32`
-##### Description:
-Convert a context item array into a UTF-32 encoded string placing it into
-the supplied buffer of specified size, and return the number of codepoints
-actually used in the conversion. If null is passed as the buffer the
-number of codepoints required is returned. Any markers in the context will
-not be included in the output buffer.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_INSUFFICENT_BUFFER`: If the buffer is not large enough.
-  `buf_size` will contain the space required. The contents of the buffer are
-  undefined.
-##### Parameters:
-- __context_items__: A pointer to the start of an array `km_core_context_item`.
-    Must be terminated with a type of `KM_CORE_CT_END`.
-- __buf__: A pointer to the buffer to place the UTF-32 string into.
-    May be null to request size calculation.
-- __buf_size__: a pointer to the result variable:
-    The size of the supplied buffer in codepoints if `buf` is given.
-    On return will be the size required if `buf` is null.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_items_to_utf32(km_core_context_item const *item,
-                              km_core_usv *buf,
-                              size_t *buf_size);
-
-#endif
-
 /*
 ```
 ### `km_core_context_set`
@@ -336,36 +149,6 @@ km_core_status
 km_core_context_set(km_core_context *context,
                    km_core_context_item const *context_items);
 
-/*
-```
-### `km_core_context_get`
-##### Description:
-Copies all items in the context into a new array and returns the new array.
-This must be disposed of by caller using `km_core_context_items_dispose`.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_NO_MEM`: In the event not enough memory can be allocated for the
-  output buffer.
-##### Parameters:
-- __context_items__: A pointer to the start of an array `km_core_context_item`.
-- __out__: a pointer to the result variable:
-    A pointer to the start of the `km_core_context_item` array containing a
-    copy of the context. Terminated with a type of `KM_CORE_CT_END`. Must be
-    disposed of with `km_core_context_items_dispose`.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_get(km_core_context const *context_items,
-                   km_core_context_item **out);
-
-#endif
-
 /*
 ```
 ### `km_core_context_clear`
@@ -381,88 +164,6 @@ KMN_API
 void
 km_core_context_clear(km_core_context *);
 
-/*
-```
-### `km_core_context_length`
-##### Description:
-Return the number of items in the context.
-##### Return:
-The number of items in the context, and will return 0 if passed a null `context`
-pointer.
-##### Parameters:
-- __context__: A pointer to an opaque context object
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-size_t
-km_core_context_length(km_core_context *);
-
-#endif
-
-/*
-```
-### `km_core_context_append`
-##### Description:
-Add more items to the end (insertion point) of the context. If these exceed the
-maximum context length the same number of items will be dropped from the
-beginning of the context.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_NO_MEM`: In the event not enough memory can be allocated to
-  grow the context buffer internally.
-##### Parameters:
-- __context__: A pointer to an opaque context object.
-- __context_items__: A pointer to the start of the `KM_CORE_CT_END` terminated
-    array of `km_core_context_item` to append.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_append(km_core_context *context,
-                      km_core_context_item const *context_items);
-
-#endif
-
-/*
-```
-### `km_core_context_shrink`
-##### Description:
-Remove a specified number of items from the end of the context, optionally
-add up to the same number of the supplied items to the front of the context.
-##### Return status:
-- `KM_CORE_STATUS_OK`: On success.
-- `KM_CORE_STATUS_INVALID_ARGUMENT`: If non-optional parameters are null.
-- `KM_CORE_STATUS_NO_MEM`: in the event it cannot allocated enough memory to grow
-  the context internally.
-##### Parameters:
-- __context__: A pointer to an opaque context object.
-- __num__: The number of items to remove from the end of context.
-- __context_items__: Pointer to the start of the `KM_CORE_CT_END` terminated
-    array of `km_core_context_item` to add to the front. Up to `num` items will
-    be prepended. This may be null if not required.
-
-```c
-*/
-
-#ifdef _KM_CORE_ACCESS_PRIVATE_CONTEXT_API
-
-KMN_API
-km_core_status
-km_core_context_shrink(km_core_context *context,
-                      size_t num,
-                      km_core_context_item const *prefix);
-
-#endif
-
 /*
 ```
 ### `km_core_context_item_list_size`

core/meson.build

@@ -29,9 +29,6 @@ python = py.find_installation()
 # For now, we use KM_CORE_LIBRARY to inject the km::core::kmx namespace
 defns += ['-DKM_CORE_LIBRARY']
 
-# See keyman_core_api_context.h
-defns += ['-D_KM_CORE_ACCESS_PRIVATE_CONTEXT_API']
-
 # #define DEBUG when we are on a debug build
 if get_option('buildtype') == 'debug'
   add_global_arguments('-DDEBUG', language : 'cpp')

core/src/action.cpp

@@ -115,13 +115,13 @@ km_core_actions * km::core::action_item_list_to_actions_object(
 
   size_t buf_size;
 
-  if((status = km_core_context_items_to_utf32(output.data(), nullptr, &buf_size)) != KM_CORE_STATUS_OK) {
+  if((status = context_items_to_utf32(output.data(), nullptr, &buf_size)) != KM_CORE_STATUS_OK) {
     return nullptr;
   }
 
   std::unique_ptr<km_core_usv[]> output_usv(new km_core_usv[buf_size]);
 
-  if((status = km_core_context_items_to_utf32(output.data(), output_usv.get(), &buf_size)) != KM_CORE_STATUS_OK) {
+  if((status = context_items_to_utf32(output.data(), output_usv.get(), &buf_size)) != KM_CORE_STATUS_OK) {
     return nullptr;
   }