Commit: 74585568b0ee7d76a88406ce67238ec3a39a9e1b - medialist-cli (git)

CLI interface to medialist (fossil mirror)

Commit MetaInfo

• Revision: 74585568b0ee7d76a88406ce67238ec3a39a9e1b (tree)
• Zeit: 2023-04-04 15:40:02
• Autor: mio <stigma@disr...>
• Commiter: mio

Log Message

Finish updating medialist info document for version 0.4

FossilOrigin-Name: f3ae10816106fa4fc5833a092293ea7065f4a7bf7eb31dfd22356f800cca4d78

Ändern Zusammenfassung

• modified: docs/medialist.info

Diff

--- a/docs/medialist.info
+++ b/docs/medialist.info
@@ -1,7 +1,7 @@
 \input texinfo                  @c -*-texinfo-*-
 
 @set VERSION 0.4
-@set UPDATED 2022-03-16
+@set UPDATED 2022-04-04
 
 @settitle MediaList @value{VERSION}
 @syncodeindex pg cp
@@ -39,7 +39,7 @@ information, visit @uref{http://creativecommons.org/publicdomain/zero/1.0/}.
 @contents
 
 @node Top
-@top MediaList
+@top Top
 
 This manual is for MediaList (version @value{VERSION}, @value{UPDATED}).
 
@@ -84,6 +84,38 @@ Some programs (e.g. the
 @uref{https://yume-neru.neocities.org/p/medialist.html, medialist suite of programs})
 use these comments as a way of providing per-file configuration.
 
+@node Constants
+@chapter Constants
+
+There are only a couple of constants present in MediaList.
+
+@table @code
+@item enum string MediaListVersion
+@pindex enum MediaListVersion
+
+This string represents the current version of MediaList, it may also
+contains a ``-dev'' suffix to indicate that you're running a development
+version which may have some known bugs.  The format is Major.Minor.Patch.
+
+A ``Major'' version change represents the removal or modification of an
+existing API.  The ``Patch'' version is used only for compile-time fixes.
+The ``Minor'' version represents all other changes.
+
+@item enum int[3] MediaListVersionA
+@pindex enum MediaListVersionA
+
+This static array represents the version of MediaList you're compiling
+against.  Unlike the string version, this doesn't have a method for
+determining a development version.  The format is still Major.Minor.Patch.
+
+@end table
+
+@cartouche
+@b{Note}: MediaList hasn't reached a ``1.0.0'' version yet, each new
+release is only incrementing the ``Minor'' version.  These ``pre-Major''
+versions can still contain modifications to (or the removal of) APIs.
+@end cartouche
+
 @node Data Types
 @chapter Data Types
 
@@ -391,38 +423,52 @@ code.
 
 @table @code
 @item MediaList* ml_open_list(string filePath)
+@item MediaList* ml_open_list(string filePath, out MLError error) nothrow
 @pindex ml_open_list
 
 This function will allocate the memory for a @code{MediaList} structure,
 returning @code{null} if the allocation fails.
 
-@item void ml_free_list(MediaList* list)
+If the underlying file for the list doesn't exist (i.e. a new list is being
+created), then the file will be created with the default headers.
+
+The nothrow version will return provide a @code{MLError} in the event of
+an error when creating the new file, otherwise it will be equal to
+@code{MLError.success}.
+
+@item void ml_free_list(MediaList* list) nothrow
 @pindex ml_free_list
 
-This function will free the allocated memory for a @code{MediaList} structure.
+This function will free the allocated memory for a @code{MediaList}
+structure created by @code{ml_open_list}.
 
-@item MediaListHeader[] ml_fetch_headers(MediaList* list, MLError* error = null)
+@item MediaListHeader[] ml_fetch_headers(MediaList* list)
+@item MediaListHeader[] ml_fetch_headers(MediaList* list, out MLError error) nothrow
 @pindex ml_fetch_headers
 
 This function will fetch all of the headers from the list's mTSV file. An
 optional @code{error} parameter is provided for error handling.
 
-@item MediaListItem ml_fetch_item(MediaList* list, size_t id, MLError* error = null)
+@item MediaListItem ml_fetch_item(MediaList* list, size_t id)
+@item MediaListItem ml_fetch_item(MediaList* list, size_t id, out MLError error) nothrow
 @pindex ml_fetch_item
 
 Fetch a single item from the list. 
 
-@item MediaListItem[] ml_fetch_items(MediaList* list, MLError* error, size_t[] ids...)
+@item MediaListItem[] ml_fetch_items(MediaList* list, size_t[] ids...)
+@item MediaListItem[] ml_fetch_items(MediaList* list, out MLError err, size_t[] ids ...) nothrow
 @pindex ml_fetch_items
 
 Fetch multiple items from a list.
 
-@item MediaListItem[] ml_fetch_all(MediaList* list, MLError* error = null)
+@item MediaListItem[] ml_fetch_all(MediaList* list)
+@item MediaListItem[] ml_fetch_all(MediaList* list, out MLError error) nothrow
 @pindex ml_fetch_all
 
 Fetch and return all of the items in a list.
 
-@item MLError ml_send_command(MediaList* list, MLCommand command, string[] args)
+@item void ml_send_command(MediaList* list, MLCommand command, string[] args)
+@item void ml_send_command(MediaList* list, MLCommand command, string[] args, out MLError error) nothrow
 @pindex ml_send_command
 
 Send a command to the list. This is how all of the editing of the list is done.
@@ -484,8 +530,8 @@ int main(string[] args)
   ml_send_command(list, MLCommand.add, ["Item 2", "10/100"], err);
   if (MLError.success != err) print_error(err);
 
-  ml_send_command(list, MLCommand.add, ["Item 3", null, "PLAN-TO-WATCH"],
-                  err);
+  ml_send_command(list, MLCommand.add,
+                  ["Item 3", null, "PLAN-TO-WATCH"], err);
   if (MLError.success != err) print_error(err);
 
   ml_send_command(list, MLCommand.add, ["Item 4", "10/10", "COMPLETE"],
@@ -504,12 +550,12 @@ int main(string[] args)
   if (MLError.success != err) print_error(err);
 
   ml_send_command(list, MLCommand.update,
-                  ["4", "start_date::2021-11-25", "end_date::2022-02-13"],
-                  err);
+                 ["4","start_date::2021-11-25","end_date::2022-02-13"],
+                 err);
   if (MLError.success != err) print_error(err);
 
-  ml_send_command(list, MLCommand.update, ["3", "title::The Third Item"],
-                  err);
+  ml_send_command(list, MLCommand.update,
+                 ["3", "title::The Third Item"], err);
   if (MLError.success != err) print_error(err);
 
   /* Fetch an item and write the details out. */