release(4.1.0): deprecate procedural Try functions, keep Option

- Deprecate Result-based Try functions (Try_To_Result, Try_To_Functional_Result,
  Try_To_Any_Result_With_Param, Try_To_Result_With_Param) in favor of
  declarative Map_To_Result/Map_To_Result_With_Param
- Keep Option-based Try functions (Try_To_Functional_Option,
  Try_To_Option_With_Param) - valid for "probe" operations with defaults
- Reimplement To_Result/To_Option child packages with inline exception
  handling to eliminate internal deprecation warnings
- Add "When to Use Option" documentation to functional-try.ads
- Add GNATPP-TEMP to .gitignore
- Add tools/puml/ for reference project tooling

Author: abitofhelp

.gitignore

@@ -277,3 +277,6 @@ ENV/
 ###############################################################################
 # Temporary 
 ###############################################################################
+
+# GNAT Pretty Print temp files
+*__GNATPP-TEMP

CHANGELOG.md

@@ -1,11 +1,11 @@
 # Changelog
 
-**Version:** 4.0.0  
-**Date:** December 12, 2025  
+**Version:** 4.1.0
+**Date:** December 18, 2025
 **SPDX-License-Identifier:** BSD-3-Clause<br>
 **License File:** See the LICENSE file in the project root.<br>
-**Copyright:** © 2025 Michael Gardner, A Bit of Help, Inc.<br>  
-**Status:** Released  
+**Copyright:** © 2025 Michael Gardner, A Bit of Help, Inc.<br>
+**Status:** Released
 
 All notable changes to this project will be documented in this file.
 
@@ -14,9 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [4.1.0] - 2025-12-18
+
 ### Deprecated
 
-#### Result-based Try functions
+#### Result-based Try functions (procedural Map_Exception pattern)
 - `Try_To_Result` - Use `Functional.Try.Map_To_Result`
 - `Try_To_Any_Result_With_Param` - Use `Functional.Try.Map_To_Result_With_Param`
 - `Try_To_Functional_Result` - Use `Functional.Try.Map_To_Result`
@@ -27,13 +31,18 @@ maintainable than procedural `Map_Exception` functions (code). The Map
 versions use a mapping array that is self-documenting and allows multiple
 exception-to-error-kind discriminations without if/elsif chains.
 
-#### Option-based Try functions
-- `Try_To_Functional_Option` - Use `Functional.Try.Map_To_Result` with default
-- `Try_To_Option_With_Param` - Use `Functional.Try.Map_To_Result_With_Param` with default
+**Note:** Option-based Try functions (`Try_To_Functional_Option`,
+`Try_To_Option_With_Param`) are NOT deprecated. They serve valid use cases
+for "probe" operations with sensible defaults where error details don't matter.
+
+### Changed
 
-**Rationale:** Discarding exception context loses debuggability. Prefer
-Result with explicit `Unwrap_Or` at call site to preserve error information
-while still providing default fallback behavior.
+- `Functional.Try.To_Result` - Reimplemented with inline exception handling
+  instead of delegating to deprecated `Try_To_Functional_Result`. This eliminates
+  deprecation warnings when building the functional library itself.
+- `Functional.Try.To_Option` - Reimplemented with inline exception handling
+  instead of delegating to `Try_To_Functional_Option` (consistency).
+- Added "When to Use Option" documentation section to `functional-try.ads`
 
 ---
 

alire.toml

@@ -1,6 +1,6 @@
 name = "functional"
 description = "Functional Programming Library for Ada 2022"
-version = "4.0.0"
+version = "4.1.0"
 
 authors = ["A Bit of Help, Inc. - Michael Gardner"]
 maintainers = ["A Bit of Help, Inc. - Michael Gardner <mjgardner@abitofhelp.com>"]

src/functional-try-to_option.adb

@@ -8,15 +8,16 @@ pragma Ada_2022;
 
 package body Functional.Try.To_Option is
 
+   ---------
+   -- Run --
+   ---------
+
    function Run return T_Option.Option is
-      --  Instantiate the core generic function
-      function Try_Impl is new
-        Try_To_Functional_Option
-          (T          => T,
-           Option_Pkg => T_Option,
-           Action     => Action);
    begin
-      return Try_Impl;
+      return T_Option.New_Some (Action);
+   exception
+      when others =>
+         return T_Option.None;
    end Run;
 
 end Functional.Try.To_Option;

src/functional-try-to_option.ads

@@ -1,17 +1,24 @@
 pragma Ada_2022;
 --  ===========================================================================
---  Functional.Try.To_Option - Child package for backwards compatibility
+--  Functional.Try.To_Option - Simple Exception-to-Option Bridge
 --  ===========================================================================
 --  Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
 --  SPDX-License-Identifier: BSD-3-Clause
 --
 --  Purpose:
---    Provides backwards-compatible API for existing tests.
---    Wraps the generic function Functional.Try.Try_To_Functional_Option.
+--    Bridges exception-based code to Option types. Returns Some(value) on
+--    success, None on any exception.
 --
---  Note:
---    New code should use Functional.Try.Try_To_Functional_Option directly
---    for cleaner syntax. This child package exists for test compatibility.
+--  When to Use:
+--    - "Probe" operations where you have a sensible default (Is_TZif_File, etc.)
+--    - "Best effort" reads with Unwrap_Or fallback (Read_Version, etc.)
+--    - Recursive traversals that skip on access errors (Count_Files, etc.)
+--    - When failure is expected/normal, not an error condition
+--
+--  When NOT to Use:
+--    - When error details matter for logging/debugging
+--    - When different exceptions need different handling
+--    - For critical operations where failures should be explicit
 --
 --  ===========================================================================
 

src/functional-try-to_result.adb

@@ -8,17 +8,16 @@ pragma Ada_2022;
 
 package body Functional.Try.To_Result is
 
+   ---------
+   -- Run --
+   ---------
+
    function Run return T_Result.Result is
-      --  Instantiate the core generic function
-      function Try_Impl is new
-        Try_To_Functional_Result
-          (T             => T,
-           E             => E,
-           Result_Pkg    => T_Result,
-           Map_Exception => Map_Exception,
-           Action        => Action);
    begin
-      return Try_Impl;
+      return T_Result.Ok (Action);
+   exception
+      when Occ : others =>
+         return T_Result.New_Error (Map_Exception (Occ));
    end Run;
 
 end Functional.Try.To_Result;

src/functional-try-to_result.ads

@@ -1,17 +1,23 @@
 pragma Ada_2022;
 --  ===========================================================================
---  Functional.Try.To_Result - Child package for backwards compatibility
+--  Functional.Try.To_Result - Simple Exception-to-Result Bridge
 --  ===========================================================================
 --  Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
 --  SPDX-License-Identifier: BSD-3-Clause
 --
 --  Purpose:
---    Provides backwards-compatible API for existing tests.
---    Wraps the generic function Functional.Try.Try_To_Result.
+--    Bridges exception-based code to Result types using a procedural
+--    Map_Exception function for exception-to-error conversion.
 --
---  Note:
---    New code should use Functional.Try.Try_To_Functional_Result directly
---    for cleaner syntax. This child package exists for test compatibility.
+--  When to Use:
+--    - Simple 1:1 exception-to-error mapping with procedural logic
+--    - When you need to inspect Exception_Occurrence for custom error building
+--    - Legacy code integration
+--
+--  When to Use Map_To_Result Instead:
+--    - Declarative exception mappings (data, not code)
+--    - Multiple exception types mapping to different error kinds
+--    - Self-documenting mapping tables
 --
 --  ===========================================================================
 

src/functional-try.ads

@@ -29,6 +29,14 @@ pragma Ada_2022;
 --    - File paths, user IDs, configuration, etc.
 --    - Supports indefinite types like String
 --
+--  When to Use Option (Try_To_Functional_Option / Try_To_Option_With_Param):
+--    When you don't need error details and have a sensible default
+--    - "Probe" operations: Is_TZif_File, File_Exists, etc.
+--    - "Best effort" reads: Read_Version with Unwrap_Or("unknown")
+--    - Recursive traversals: Count_Files with Unwrap_Or(0) on access errors
+--    - Pattern: Try action, on ANY exception return None, then Unwrap_Or(default)
+--    - Appropriate when failure is expected/normal, not an error condition
+--
 --  Functions:
 --    Try_To_Result                   - No-param bridge to any Result type
 --    Try_To_Any_Result_With_Param    - Parameterized bridge to any Result type
@@ -127,8 +135,7 @@ is
       type T is private;
       with package Option_Pkg is new Functional.Option (T => T);
       with function Action return T;
-   function Try_To_Functional_Option return Option_Pkg.Option
-     with Obsolescent => "Use Functional.Try.Map_To_Result with default";
+   function Try_To_Functional_Option return Option_Pkg.Option;
 
    --  ========================================================================
    --  Try_To_Result_With_Param - Parameterized Result bridge
@@ -161,7 +168,6 @@ is
       type Param (<>) is private;
       with package Option_Pkg is new Functional.Option (T => T);
       with function Action (P : Param) return T;
-   function Try_To_Option_With_Param (P : Param) return Option_Pkg.Option
-     with Obsolescent => "Use Functional.Try.Map_To_Result_With_Param with default";
+   function Try_To_Option_With_Param (P : Param) return Option_Pkg.Option;
 
 end Functional.Try;