Removed need for initialize/shutdown, improved documentation slightly

4 files changed, 87 insertions, 114 deletions

diff --git a/example/aao_example.adb b/example/aao_example.adb
index 7d12b56..fd32e38 100644
--- a/example/aao_example.adb
+++ b/example/aao_example.adb
@@ -27,12 +27,9 @@ procedure AAO_Example is
 
 begin
 
-    --  Initialize
 
     TIO.Put_Line ("libao example program");
 
-    Libao.Startup;
-
 
     --  Setup for default driver
 
@@ -89,12 +86,11 @@ begin
 
     --  Close and shutdown
 
-    --  Technically the binding will take care of closing open devices at shutdown,
-    --  but it is always good practice to close them anyway.
+    --  Technically the binding will take care of closing open devices at the
+    --  end of runtime, but it is always good practice to close them anyway.
 
     Libao.Close (My_Device);
 
-    Libao.Shutdown;
 
 end AAO_Example;
 
diff --git a/readme.txt b/readme.txt
index a0a3233..8cb62c2 100644
--- a/readme.txt
+++ b/readme.txt
@@ -8,15 +8,21 @@ Overview
 --------
 
 This a thick binding, so the rough edges of C have all been filed off. In
-particular ao_option/Option_List objects are automatically deallocated when
-they go out of scope, and any remaining open ao_device/Device objects are
-automatically closed when libao is shut down.
+particular:
+
+ * ao_initialize/ao_shutdown are now automatic
+ * ao_option/Option_List objects are deallocated when they go out of scope
+ * ao_device/Device objects are automatically closed upon program end
+ * All error codes have been converted to exceptions
+
+A short example program is available in /example/.
 
 
 Dependencies
 ------------
 
-GNAT (build)
+An Ada 2012 compiler and standard library (build)
+A C compiler and standard library (build)
 gprbuild (build)
 libao (run)
 
@@ -38,7 +44,7 @@ programs provided.
 Further Information
 -------------------
 
-API of libao:
+C API of libao:
 https://xiph.org/ao/doc/libao-api.html
 
 
@@ -49,6 +55,8 @@ This binding and the short Ada example were written by Jedidiah Barber.
 
 The short C example program was written by Stan Seibert.
 
-All code is released into the public domain.
+All code of this binding and example programs is released into the public
+domain. Consult unlicense.txt and the header of the C example program for
+further information.
 
 
diff --git a/src/libao.adb b/src/libao.adb
index c1491c2..e10582d 100644
--- a/src/libao.adb
+++ b/src/libao.adb
@@ -19,6 +19,10 @@ use type
 package body Libao is
 
 
+    ------------------------
+    --  Functions From C  --
+    ------------------------
+
     procedure ao_initialize;
     pragma Import (C, ao_initialize, "ao_initialize");
     pragma Inline (ao_initialize);
@@ -28,8 +32,6 @@ package body Libao is
     pragma Inline (ao_shutdown);
 
 
-
-
     function ao_append_option
            (Options : in out System.Address;
             Key     : in     Interfaces.C.char_array;
@@ -83,8 +85,6 @@ package body Libao is
     pragma Inline (ao_close);
 
 
-
-
     function ao_driver_id
            (Short_Name : in Interfaces.C.char_array)
         return Interfaces.C.int;
@@ -115,8 +115,6 @@ package body Libao is
     pragma Inline (ao_file_extension);
 
 
-
-
     function ao_is_big_endian
         return Interfaces.C.int;
     pragma Import (C, ao_is_big_endian, "ao_is_big_endian");
@@ -295,6 +293,10 @@ package body Libao is
 
 
 
+    -----------------------------------
+    --  Controlled Type Subprograms  --
+    -----------------------------------
+
     procedure Adjust
            (This : in out Option_List)
     is
@@ -329,9 +331,22 @@ package body Libao is
         Interfaces.C.Strings.Free (This.C_Struct.Matrix);
     end Finalize;
 
+    procedure Finalize
+           (This : in out Final_Controller) is
+    begin
+        for Addy of Device_List loop
+            Do_Close (Addy);
+        end loop;
+        ao_shutdown;
+    end Finalize;
 
 
 
+
+    ---------------------------------
+    --  Data Types and Structures  --
+    ---------------------------------
+
     function Kind
            (Attributes : in Info)
         return Output_Kind
@@ -409,8 +424,6 @@ package body Libao is
     end Option_Key;
 
 
-
-
     function Image_Length
            (Channel : in Channel_Mnemonic)
         return Positive is
@@ -477,30 +490,9 @@ package body Libao is
 
 
 
-    function Is_Alive
-        return Boolean is
-    begin
-        return Alive_Status;
-    end Is_Alive;
-
-    procedure Startup is
-    begin
-        ao_initialize;
-        Device_List.Clear;
-        Alive_Status := True;
-    end Startup;
-
-    procedure Shutdown is
-    begin
-        for Addy of Device_List loop
-            Do_Close (Addy);
-        end loop;
-        ao_shutdown;
-        Alive_Status := False;
-    end Shutdown;
-
-
-
+    --------------------------------------
+    --  Device Setup/Playback/Teardown  --
+    --------------------------------------
 
     procedure Do_Append
            (Ptr   : in out System.Address;
@@ -657,6 +649,10 @@ package body Libao is
 
 
 
+    --------------------------
+    --  Driver Information  --
+    --------------------------
+
     function Driver_ID
            (Short_Name : in String)
         return Driver_ID_Number
@@ -730,6 +726,10 @@ package body Libao is
 
 
 
+    ---------------------
+    --  Miscellaneous  --
+    ---------------------
+
     function Is_Big_Endian
         return Boolean is
     begin
@@ -741,6 +741,12 @@ package body Libao is
     end Is_Big_Endian;
 
 
+
+
+begin
+
+    ao_initialize;
+
 end Libao;
 
 
diff --git a/src/libao.ads b/src/libao.ads
index 1bdb142..9e1cde1 100644
--- a/src/libao.ads
+++ b/src/libao.ads
@@ -15,9 +15,9 @@ private with
 package Libao is
 
 
-    -----------------------
-    --  Data Structures  --
-    -----------------------
+    ---------------------------------
+    --  Data Types and Structures  --
+    ---------------------------------
 
     type Driver_ID_Number is new Natural;
 
@@ -35,44 +35,36 @@ package Libao is
 
     function Kind
            (Attributes : in Info)
-        return Output_Kind
-    with Pre => Is_Alive;
+        return Output_Kind;
 
     function Name
            (Attributes : in Info)
-        return String
-    with Pre => Is_Alive;
+        return String;
 
     function Short_Name
            (Attributes : in Info)
-        return String
-    with Pre => Is_Alive;
+        return String;
 
     function Preferred_Byte_Format
            (Attributes : in Info)
-        return Endianness
-    with Pre => Is_Alive;
+        return Endianness;
 
     function Priority_Level
            (Attributes : in Info)
-        return Positive
-    with Pre => Is_Alive;
+        return Positive;
 
     function Comment
            (Attributes : in Info)
-        return String
-    with Pre => Is_Alive;
+        return String;
 
     function Option_Count
            (Attributes : in Info)
-        return Natural
-    with Pre => Is_Alive;
+        return Natural;
 
     function Option_Key
            (Attributes : in Info;
             Index      : in Positive)
-        return String
-    with Pre => Is_Alive;
+        return String;
 
 
     type Option_List is tagged private;
@@ -139,24 +131,6 @@ package Libao is
 
 
 
-    ------------------------------
-    --  Library Setup/Teardown  --
-    ------------------------------
-
-    function Is_Alive
-        return Boolean;
-
-    procedure Startup
-    with Pre => not Is_Alive,
-        Post => Is_Alive;
-
-    procedure Shutdown
-    with Pre => Is_Alive,
-        Post => not Is_Alive;
-
-
-
-
     --------------------------------------
     --  Device Setup/Playback/Teardown  --
     --------------------------------------
@@ -164,20 +138,17 @@ package Libao is
     procedure Append
            (This  : in out Option_List;
             Key   : in     String;
-            Value : in     String)
-    with Pre => Is_Alive;
+            Value : in     String);
 
     procedure Append_Global_Option
            (Key   : in String;
-            Value : in String)
-    with Pre => Is_Alive;
+            Value : in String);
 
     function Open_Live
            (Driver_ID : in Driver_ID_Number;
             Format    : in Sample_Format;
             Options   : in Option_List'Class)
-        return Device
-    with Pre => Is_Alive;
+        return Device;
 
     function Open_File
            (Driver_ID : in Driver_ID_Number;
@@ -185,17 +156,14 @@ package Libao is
             Format    : in Sample_Format;
             Options   : in Option_List'Class;
             Overwrite : in Boolean := False)
-        return Device
-    with Pre => Is_Alive;
+        return Device;
 
     procedure Play
            (Output_Device : in Device;
-            Samples       : in Data_Buffer)
-    with Pre => Is_Alive;
+            Samples       : in Data_Buffer);
 
     procedure Close
-           (Output_Device : in out Device)
-    with Pre => Is_Alive;
+           (Output_Device : in out Device);
 
 
 
@@ -206,26 +174,21 @@ package Libao is
 
     function Driver_ID
            (Short_Name : in String)
-        return Driver_ID_Number
-    with Pre => Is_Alive;
+        return Driver_ID_Number;
 
     function Default_Driver_ID
-        return Driver_ID_Number
-    with Pre => Is_Alive;
+        return Driver_ID_Number;
 
     function Driver_Info
            (Ident : in Driver_ID_Number)
-        return Info
-    with Pre => Is_Alive;
+        return Info;
 
     function Driver_Info_List
-        return Info_Array
-    with Pre => Is_Alive;
+        return Info_Array;
 
     function File_Extension
            (Ident : in Driver_ID_Number)
-        return String
-    with Pre => Is_Alive;
+        return String;
 
 
 
@@ -235,17 +198,13 @@ package Libao is
     ---------------------
 
     function Is_Big_Endian
-        return Boolean
-    with Pre => Is_Alive;
+        return Boolean;
 
 
 private
 
 
     pragma Linker_Options ("-lao");
-    pragma Inline (Is_Alive);
-
-
 
 
     procedure Do_Append
@@ -257,8 +216,6 @@ private
            (Ptr : in System.Address);
 
 
-
-
     type Device is record
         Ptr : System.Address;
     end record;
@@ -302,10 +259,7 @@ private
            (This : in out Sample_Format);
 
 
-
-
-    Alive_Status : Boolean := False;
-
+    --  Keep track of
     package Address_Vectors is new Ada.Containers.Vectors
        (Index_Type   => Positive,
         Element_Type => System.Address,
@@ -314,6 +268,15 @@ private
     Device_List : Address_Vectors.Vector := Address_Vectors.Empty_Vector;
 
 
+    --  The clunky way of ensuring that libao is always shut down properly
+    type Final_Controller is new Ada.Finalization.Controlled with null record;
+
+    overriding procedure Finalize
+           (This : in out Final_Controller);
+
+    Cleanup : Final_Controller;
+
+
 end Libao;