APL-CORE: June 2022 Release of APL 2022.1 compilant core engine (2022…

….1.0)

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2022.1.0]
+
+This release adds support for version 2022.1 of the APL specification.
+
+### Added
+
+- Alpha feature: New APL Extensions lifecycle.
+- Alpha feature: Added new encryption and webflow interfaces into the extension library.
+- Added log id to help to track logs between multiple experiences.
+- Video now can be muted and unmuted dynamically.
+
+### Changed
+
+- Bug fixes.
+- Build improvements.
+- Fixed typos and cleanup formatting.
+- Improved localization handling within core.
+- Performance improvements.
+- Update Yoga dependency to 1.19.
+
 ## [1.9.1]
 
 ### Changed

CMakeLists.txt

@@ -11,6 +11,10 @@
 # express or implied. See the License for the specific language governing
 # permissions and limitations under the License.
 
+# Use the FetchContent cmake module to unpack Yoga.  This may not be available
+# on older systems
+include(FetchContent OPTIONAL RESULT_VARIABLE HAS_FETCH_CONTENT)
+
 cmake_minimum_required(VERSION 3.5)
 
 project(APLCoreEngine

THIRD-PARTY-NOTICES.txt

@@ -145,7 +145,7 @@ SOFTWARE
 
 ------
 
-** yoga 1.16; version 1.16.0 -- https://yogalayout.com/
+** yoga 1.19; version 1.19.0 -- https://yogalayout.com/
 Copyright (c) Facebook, Inc. and its affiliates.
 
 MIT License

aplcore/CMakeLists.txt

@@ -52,7 +52,8 @@ endif()
 if (TARGET yoga)
     add_dependencies(apl yoga)
 endif()
-    add_dependencies(apl pegtl-build)
+
+add_dependencies(apl pegtl-build)
 
 # When not using the system rapidjson build the library, add a dependency on the build step
 if (NOT USE_SYSTEM_RAPIDJSON)
@@ -110,9 +111,13 @@ target_include_directories(apl
         $<BUILD_INTERFACE:${YOGA_INCLUDE}>
 )
 
-target_link_libraries(apl
+if (USE_PROVIDED_YOGA_INLINE)
+    target_sources(apl PRIVATE ${YOGA_SRC})
+else()
+    target_link_libraries(apl
         PRIVATE
             libyoga)
+endif()
 
 # include the alexa extensions library
 if (ENABLE_ALEXAEXTENSIONS)
@@ -158,19 +163,21 @@ install(DIRECTORY ${RAPIDJSON_INCLUDE}/rapidjson
         FILES_MATCHING PATTERN "*.h")
 endif()
 
-if (NOT YOGA_EXTERNAL_LIB AND NOT USE_SYSTEM_YOGA)
+if (USE_PROVIDED_YOGA_AS_LIB)
     # We built the bundled yoga lib, install it
     install(FILES ${YOGA_LIB}
         DESTINATION lib)
 endif()
 
+if (NOT USE_PROVIDED_YOGA_INLINE)
 set_target_properties(apl PROPERTIES
     EXPORT_NAME
         core
     INTERFACE_LINK_LIBRARIES
         # Only set this for builds, the find module will handle the other cases
         $<BUILD_INTERFACE:${YOGA_LIB}>
 )
+endif()
 
 export(
     EXPORT

aplcore/include/apl/action/action.h

@@ -58,25 +58,25 @@ class Action : public std::enable_shared_from_this<Action>,
     /**
      * Make a generic action.  The StartFunc runs immediately.  If you don't pass a starting function,
      * the action is resolved immediately.
-     * @param timers
-     * @param func
+     * @param timers Timer reference
+     * @param func The starting function to execute immediately.
      * @return The action
      */
     static ActionPtr make(const TimersPtr& timers, StartFunc func = nullptr);
 
     /**
      * Make an action that fires after a delay.  If you don't pass a starting function,
      * the action resolves after the delay.
-     * @param timers
-     * @param delay
-     * @param func
+     * @param timers Timer reference
+     * @param delay Delay in milliseconds to wait before running the starting function.
+     * @param func The starting function to execute.
      * @return The action
      */
     static ActionPtr makeDelayed(const TimersPtr& timers, apl_duration_t delay, StartFunc func = nullptr);
 
     /**
      * Make an action that resolves after all of the child actions resolve.
-     * @param timers
+     * @param timers Timer reference
      * @param actionList A list of actions.
      * @return The tail of this action
      */
@@ -85,7 +85,7 @@ class Action : public std::enable_shared_from_this<Action>,
     /**
      * Make an action that resolves after any of the child actions resolve.
      * The other child actions are terminated.
-     * @param timers
+     * @param timers Timer reference
      * @param actionList A list of actions
      * @return The tail of this action.
      */
@@ -94,7 +94,7 @@ class Action : public std::enable_shared_from_this<Action>,
     /**
      * Make an action that runs an animation.  The animator function is called as time is advanced
      * up to and including when the duration is reached.  It is _not_ called for a time of zero.
-     * @param timers
+     * @param timers Timer reference
      * @param duration The duration of the animation.
      * @param animator The function to call up to and including when the duration time is reached.
      * @return The animation action
@@ -106,7 +106,7 @@ class Action : public std::enable_shared_from_this<Action>,
     /**
      * Wrap provided action with another one that will call a callback when provided resolved. If
      * provided action is terminated wrap action will also be terminated.
-     * @param timers
+     * @param timers Timer reference
      * @param action action to wrap.
      * @param callback Callback to call.
      * @return Wrap action.
@@ -151,7 +151,7 @@ class Action : public std::enable_shared_from_this<Action>,
     /**
      * Resolve with a rect. Used to pass back a bounds for the first line of a text component
      * during line karaoke.
-     * @param argument
+     * @param argument A rectangle
      */
     void resolve(const Rect& argument);
 
@@ -230,7 +230,7 @@ class ActionRef  {
 
     /**
      * Resolve the action with a union
-     * @param argument
+     * @param argument A rectangle
      */
     void resolve(const Rect& argument) const {
         if (mPtr)
@@ -293,7 +293,7 @@ class ActionRef  {
      * @deprecated
      * @return True if there is no action associated with this action ref.
      */
-    bool isEmpty() const { return empty(); }
+    APL_DEPRECATED bool isEmpty() const { return empty(); }
 
     /**
      * Attach a chunk of user data to this action

aplcore/include/apl/action/scrollaction.h

@@ -37,7 +37,7 @@ class ScrollAction : public AnimatedScrollAction {
     /**
      * @param timers Timer reference.
      * @param command Command that spawned this action.
-     * @return
+     * @return A scroll action or null if not needed.
      */
     static std::shared_ptr<ScrollAction> make(const TimersPtr& timers,
                                               const std::shared_ptr<CoreCommand>& command);
@@ -48,7 +48,7 @@ class ScrollAction : public AnimatedScrollAction {
      * @param target component to perform action on.
      * @param targetDistance Object containing Dimension representing distance to be scrolled.
      * @param duration scrolling duration.
-     * @return
+     * @return The scroll action or null if it is not needed.
      */
     static std::shared_ptr<ScrollAction> make(const TimersPtr& timers,
                                               const ContextPtr& context,

aplcore/include/apl/action/scrolltoaction.h

@@ -40,7 +40,7 @@ class ScrollToAction : public AnimatedScrollAction {
      * @param timers Timer reference.
      * @param command Command that spawned this action.
      * @param target Component to scroll to.
-     * @return
+     * @return The scroll to action or null if it is not needed.
      */
     static std::shared_ptr<ScrollToAction> make(const TimersPtr& timers,
                                                 const std::shared_ptr<CoreCommand>& command,
@@ -51,7 +51,7 @@ class ScrollToAction : public AnimatedScrollAction {
      * @param command Command that spawned this action.
      * @param subBounds Bounds within the target to scroll to.
      * @param target Component to scroll to.
-     * @return
+     * @return The scroll to action or null if it is not needed.
      */
     static std::shared_ptr<ScrollToAction> make(const TimersPtr& timers,
                                                 const std::shared_ptr<CoreCommand>& command,
@@ -66,7 +66,7 @@ class ScrollToAction : public AnimatedScrollAction {
      * @param subBounds Bounds within the target to scroll to.
      * @param context Target context.
      * @param target Component to scroll to.
-     * @return
+     * @return The scroll to action or null if it is not needed.
      */
     static std::shared_ptr<ScrollToAction> make(const TimersPtr& timers,
                                                 const CommandScrollAlign& align,
@@ -79,7 +79,7 @@ class ScrollToAction : public AnimatedScrollAction {
      * @param timers Timer reference.
      * @param target Component to scroll to.
      * @param duration scrolling duration.
-     * @return
+     * @return The scroll to action or null if it is not needed.
      */
     static std::shared_ptr<ScrollToAction> makeUsingSnap(const TimersPtr& timers,
                                                          const CoreComponentPtr& target,

aplcore/include/apl/animation/easing.h

@@ -48,7 +48,7 @@ class Easing : public ObjectData {
 
     /**
      * Evaluate the easing curve at a given time between 0 and 1.
-     * @param time
+     * @param time The parameterized time
      * @return The value
      */
     virtual float calc(float time) = 0;

aplcore/include/apl/animation/easinggrammar.h

@@ -21,6 +21,7 @@
 
 #include "apl/animation/coreeasing.h"
 #include "apl/utils/log.h"
+#include "apl/utils/stringfunctions.h"
 
 namespace apl {
 
@@ -29,6 +30,10 @@ namespace easinggrammar {
 namespace pegtl = tao::TAO_PEGTL_NAMESPACE;
 using namespace pegtl;
 
+/**
+ * \cond ShowColorGrammar
+ */
+
 /**
  * This grammar assumes that all space characters have been removed.
  *
@@ -93,7 +98,7 @@ template<> struct action<floatnum>
 {
     template< typename Input >
     static void apply(const Input& in, easing_state& state) {
-        state.args.push_back(std::stof(in.string()));
+        state.args.push_back(sutil::stof(in.string()));
     }
 };
 
@@ -309,6 +314,9 @@ template<> struct action< scurve >
         state.segments.emplace_back(EasingSegment(kSCurveSegment, state.startIndex));
     }
 };
-}
+/**
+ * \endcond
+ */
+} // namespace easinggrammar
 } // namespace apl
 #endif //_APL_EASING_GRAMMAR_H

aplcore/include/apl/apl.h

@@ -25,9 +25,10 @@
 #include "rapidjson/document.h"
 
 #include "apl/apl_config.h"
+#include "apl/common.h"
+
 #include "apl/action/action.h"
 #include "apl/buildTimeConstants.h"
-#include "apl/common.h"
 #include "apl/component/component.h"
 #include "apl/component/textmeasurement.h"
 #include "apl/content/configurationchange.h"
@@ -60,6 +61,8 @@
 #include "apl/primitives/mediasource.h"
 #include "apl/primitives/mediastate.h"
 #include "apl/primitives/object.h"
+#include "apl/primitives/range.h"
+#include "apl/primitives/roundedrect.h"
 #include "apl/primitives/styledtext.h"
 #include "apl/scaling/metricstransform.h"
 #include "apl/touch/pointerevent.h"
@@ -69,6 +72,7 @@
 
 #ifdef ALEXAEXTENSIONS
 #include "apl/extension/extensionmediator.h"
+#include "apl/extension/extensionsession.h"
 #endif
 
 #endif // _APL_H

aplcore/include/apl/colorgrammar/colorfunctions.h

@@ -100,9 +100,9 @@ inline uint32_t colorFromHSL(double hue, double sat, double light) {
 
 /**
  * Calculate a color value from a hexidecimal string
- * @param hex
- * @param color
- * @return
+ * @param hex The color as a hexidecimal string value
+ * @param color The calculated color will be stored in this unsigned integer.
+ * @return True if the string parsed correctly
  */
 inline bool colorFromHex(std::string hex, uint32_t& color) {
     switch (hex.length()) {
@@ -135,4 +135,4 @@ inline bool colorFromHex(std::string hex, uint32_t& color) {
 }  // namespace colorgrammar
 }  // namespace apl
 
-#endif // _COLORGRAMMAR_COLOR_FUNCTIONS_H
+#endif // _COLORGRAMMAR_COLOR_FUNCTIONS_H

aplcore/include/apl/colorgrammar/colorgrammar.h

@@ -28,6 +28,7 @@
 #include "colorfunctions.h"
 
 #include "apl/utils/log.h"
+#include "apl/utils/stringfunctions.h"
 
 namespace apl {
 namespace colorgrammar {
@@ -115,9 +116,9 @@ namespace colorgrammar {
             double value;
             if (s.back() == '%') {
                 size_t len = s.length();
-                value = stod(s.substr(0, len - 1)) * 0.01;
+                value = sutil::stod(s.substr(0, len - 1)) * 0.01;
             } else {
-                value = stod(s);
+                value = sutil::stod(s);
             }
 
             LOGF_IF(DEBUG_GRAMMAR, "Number: '%s' -> %lf", in.string().c_str(), value);

aplcore/include/apl/common.h

@@ -47,7 +47,6 @@ using apl_duration_t = double;
 // here so they can be conveniently used from any source file.
 
 class Action;
-class CharacterRanges;
 class Command;
 class Component;
 class Content;
@@ -83,9 +82,11 @@ class Timers;
 
 using ActionPtr = std::shared_ptr<Action>;
 using CommandPtr = std::shared_ptr<Command>;
+using ConstCommandPtr = std::shared_ptr<const Command>;
 using ComponentPtr = std::shared_ptr<Component>;
 using ContentPtr = std::shared_ptr<Content>;
 using ContextPtr = std::shared_ptr<Context>;
+using ConstContextPtr = std::shared_ptr<const Context>;
 using CoreComponentPtr = std::shared_ptr<CoreComponent>;
 using DataSourcePtr = std::shared_ptr<DataSource>;
 using DataSourceProviderPtr = std::shared_ptr<DataSourceProvider>;
@@ -114,7 +115,6 @@ using StyleDefinitionPtr = std::shared_ptr<StyleDefinition>;
 using StyleInstancePtr = std::shared_ptr<StyleInstance>;
 using TextMeasurementPtr = std::shared_ptr<TextMeasurement>;
 using TimersPtr = std::shared_ptr<Timers>;
-using CharacterRangesPtr = std::shared_ptr<CharacterRanges>;
 
 
 // Convenience templates for creating sets of weak and strong pointers

aplcore/include/apl/component/actionablecomponent.h

@@ -40,9 +40,9 @@ class ActionableComponent : public CoreComponent {
     void enableGestures();
 
     /**
-     * Get the touch event specific properties
-     * @param point Properties of the component segment of the event.
-     * @return The event data-binding context.
+     * Get the touch event-specific properties
+     * @param localPoint The coordinates of the local touch event
+     * @return A map of event-specific properties to be added to the data-binding context.
      */
     virtual ObjectMapPtr createTouchEventProperties(const Point& localPoint) const;