Commit: 835bc64301fa36da0feb02c20aba4f514691293a - medialist-cli (git)

CLI interface to medialist (fossil mirror)

Commit MetaInfo

• Revisión: 835bc64301fa36da0feb02c20aba4f514691293a (tree)
• Tiempo: 2023-03-30 13:05:32
• Autor: mio <stigma@disr...>
• Commiter: mio

Log Message

Update documentation for 0.4 release. Still some work to do.

FossilOrigin-Name: 117419016d47681a3d300e0537450fd80d34f281bd09d2d1572414cf13835f4f

Cambiar Resumen

• modified: docs/medialist.info
• modified: medialist.d

Diferencia incremental

--- a/docs/medialist.info
+++ b/docs/medialist.info
@@ -95,25 +95,35 @@ fields (if any), and what their purpose is.
 
 The first (and most important) structure is the @samp{MediaList} structure.
 This structure is passed to all functions that are defined in this package.
+
+It is recommended to create an instance by using the @code{ml_open_list}
+function.
+
 It has the following members:
 
 @table @samp
 @item immutable string filePath
-The absolute file path to the @dfn{TSV} file. Upon creating a @samp{MediaList}
-structure, a check is performed to see if this file exists.  If not, it is
-created.
+The absolute file path to the @dfn{TSV} file. Upon creating a
+@samp{MediaList} structure, a check is performed to see if this file exists.
+If it doesn't exist, it is created.
 
 @item immutable string listName
-The name of the ``list''.  This is determined by extracting the file name from
-the @samp{filePath}. For example, a @samp{filePath} of
-@code{/home/user/lists/mylist.tsv} would have the @samp{listName} of
+The name of the ``list''.  This is determined by extracting the file name
+from the @samp{filePath}. For example, if the  @samp{filePath} is
+@code{/home/user/lists/mylist.tsv}, then the @samp{listName} would be
 @samp{mylist}.
 
 @item bool isOpen
 A check to see if the file at @samp{filePath} is open.  All of the functions
 which edit the file will check this before doing anything.  By providing
-public access to this, I hope people can make their own functions to suit there
-needs without breaking any of the ones provided in this package.
+public access to this, I hope people can make their own functions to suit
+there needs without breaking any of the ones provided in this package.
+
+@cartouche
+@strong{NOTE:} The future of this property is being evaluated.  It requires
+people using this library to remember that it exists, and performing checks
+on its value.  It is probable that this will be removed in a future version.
+@end cartouche
 @end table
 
 @section MediaListHeader
@@ -121,8 +131,8 @@ needs without breaking any of the ones provided in this package.
 @pindex struct MediaListHeader
 
 Contains information about a particular ``header'' (i.e. column) in the
-@dfn{TSV} file. Editing these values
-@emph{does not change their values in the list}.
+@dfn{mTSV} file. Editing these values @emph{does not change their values
+in the list}.
 
 @table @samp
 @item string tsvName
@@ -130,6 +140,8 @@ The literal column name as written in the @dfn{TSV} file.
 
 @item string humanFriendlyName
 The ``human friendly name'' as determined by the comments (@pxref{mTSV}).
+If this value is set, then it should be used when displaying the header
+to people. The default value is @code{null}.
 
 @item size_t column
 The column number that this header is for. Useful if you want to read from
@@ -150,21 +162,24 @@ these values @emph{does not change their values in the list}.
 The title of this item in the list.
 
 @item string progress
-The current progress of this item in the list. By default this is @samp{-/-}.
+The current progress of this item in the list. By default this is
+@samp{-/-}.
 
 @item string status
-The current status of this item in the list. By default this is @samp{UNKNOWN}.
+The current status of this item in the list. By default this is
+@samp{UNKNOWN}.
 
 @item string startDate
 The date that this item was ``started'' on. The format for this is
-@samp{YYYY-MM-DD}. This value is automatically updated when the @samp{status}
-changes from @samp{PLAN-TO-READ} or @samp{PLAN-TO-WATCH} to @samp{READING} or
-@samp{WATCHING} respectively.
+@samp{YYYY-MM-DD}. This value is automatically updated when the
+@samp{status} changes from @samp{PLAN-TO-READ} or @samp{PLAN-TO-WATCH} to
+@samp{READING} or @samp{WATCHING} respectively.
 
 @item string endDate
 The date that this item was ``completed'' on. The format for this is
-@samp{YYYY-MM-DD}. This value is automatically updated when the @samp{status}
-changes from @samp{READING} or @samp{WATCHING} to @samp{COMPLETE}.
+@samp{YYYY-MM-DD}. This value is automatically updated when the
+@samp{status} changes from @samp{READING} or @samp{WATCHING} to
+@samp{COMPLETE}.
 
 @item string lastUpdated
 The date that this item was last updated on. The format for this is
@@ -175,21 +190,42 @@ is updated.
 A check to see if this item was initialized correctly upon being fetched.
 If it is @code{false}, then it failed and the values shouldn't be trusted.
 
+@cartouche
+@strong{NOTE}: The future of this property is undecided.  It requires that
+programmers remeber it exists, and to make use of it.  With MediaList 0.4,
+most functions throw an exception (@xref{x-mlexception,,MLException}) if
+there is an error, or return an error type (@xref{x-mlerror,,MLError}) when
+an error occurs a ``nothrow'' variant of a function has been called.
+@end cartouche
+
+@item string tsvRepresentation()
+
+This member function will convert a @samp{MediaListItem} structure in to a
+TSV representation.  This does @strong{not} add a trailing newline
+character.  The order follows the MediaList default order:
+
+@verbatim
+title, progress, status, start_date, end_date, last_updated
+@end verbatim
+
 @end table
 
-@section MLCommand
 @anchor{x-mlcommand}
+@section MLCommand
 
 @pindex enum MLCommand
 
+This enumeration type represents the type of command when sending a list of
+arguments to @code{ml_send_command} when updating a @samp{MediaList}.
+
 @table @code
 
 @item add
 @pindex MLCommand.add
 
-By providing the ``add'' command to @code{ml_send_command}, you are indicating
-that you want to append a new item to the list. The format of the arguments
-(@var{string[] args}) is as follows:
+By providing the ``add'' command to @code{ml_send_command}, you are
+indicating that you want to append a new item to the list. The format of the
+arguments (@var{string[] args}) is as follows:
 
 @verbatim
 args[0] = The new item's Title
@@ -203,24 +239,21 @@ defaults (``-/-'' for Progress and ``UNKNOWN'' for Status).
 @item delete_
 @pindex MLCommand.delete_
 
-Sending the ``delete'' command a list can have multiple meanings, depending
-on the arguments provided.  If you provide no arguments, then the entire list
-is deleted.  If at least one arugment is provided, then only the provided
-arguments are deleted.
-
-For example, to delete an entire list:
-
-@example
-ml_send_command(list, MLCommand.delete_, []);
-@end example
-
-To delete specific items from a list:
+By sending the ``delete_'' command to a list, you're saying that each item
+ID in the provided arguments should be removed from the list.  For example:
 
 @example
 ml_send_command(list, MLCommand.delete_, ["1", "10", "3"]);
 @end example
 
-Each of the items represents the item ID.  The need not be in order.
+The order of the IDs does not matter, this will remove the items with IDs 1,
+3, and 10.
+
+@cartouche
+@strong{NOTE}: Previously you could send an empty array as an argument to
+delete the list file.  This behaviour is deprecated and will be removed in
+a future version.
+@end cartouche
 
 @item update
 @pindex MLCommand.update
@@ -234,7 +267,9 @@ args[0] = Item ID (e.g. "1").
 args[n] = field::value
 @end verbatim
 
-The possible values for "field" are:
+The double colons (@samp{::}) acts as a separator.
+
+The possible values for ``field'' are:
 
 @itemize @bullet
 @item title
@@ -244,10 +279,11 @@ The possible values for "field" are:
 @item end_date
 @end itemize
 
-The "value" can include whitespace.
+The ``value'' can contain spaces.
 
 @end table
 
+@anchor{x-mlerror}
 @section MLError
 
 @pindex enum MLError
@@ -258,13 +294,14 @@ The "value" can include whitespace.
 @pindex MLError.success
 
 This value indicates that the function worked without any errors.  You can
-proceed as normal.
+proceed as normal.  The value of @samp{success} is 0.
 
 @item invalidArgs
 @pindex MLError.invalidArgs
 
 This value indicates that the arguments provided weren't sufficient.  For
-example, sending an empty array with the @code{MLCommand.add} command.
+example, sending an empty array with the @code{MLCommand.add} command.  The
+value of @samp{invalidArgs} is 1.
 
 @item fileAlreadyOpen
 @pindex MLError.fileAlreadyOpen
@@ -272,23 +309,79 @@ example, sending an empty array with the @code{MLCommand.add} command.
 This error is returned when a @code{MediaList} structure is in an ``open''
 state.  All the functions provided in this package check the file isn't
 open before reading/writing.  Should you choose to extend this package
-by writing your own functions, this can prevent accidental read/write errors.
+by writing your own functions, this can prevent accidental read/write
+errors.  The value of @samp{fileAlreadyOpen} is 2.
 
 @item fileReadError
 @pindex MLError.fileReadError
 
-An error was encountered when reading the list file.
+An error was encountered when reading the list file. The value for
+@samp{fileReadError} is 3.
 
 @item itemNotFound
 @pindex MLError.itemNotFound
 
-A requested item (either @code{ml_fetch_item} or @code{ml_fetch_items}) could
-not be found.
+A requested item (by @code{ml_fetch_item} or @code{ml_fetch_items}) could
+not be found.  The value of @samp{itemNotFound} is 4.
+
+@item permissionError
+@pindex MLError.permissionError
+
+When trying to create or open the file for a @code{MediaList}, we
+encountered a permission error and couldn't open the file.  The value for
+@samp{permissionError} is 5.
 
 @item unknownCommand
 @pindex MLError.unknownCommand
 
-An unknown command was provided to @code{ml_send_command}.
+An unknown command was provided to the @var{command} parameter for the
+@code{ml_send_command} function.  The value of @samp{unknownCommand} is 6.
+
+@item unspecifiedError
+@pindex MLError.unspecifiedError
+
+An unknown error occurred.  This is used as a fallback for operating system
+and Phobos exceptions.  The value of @samp{unspecifiedError} is always
+equal to @code{MLError.max}.
+
+@end table
+
+@anchor{x-mlexception}
+@section MLException
+
+@pindex class MLException
+
+A custom MediaList Exception class which is used for error reporting in
+the functions which throw (rather than the @code{nothrow} variants).
+
+@table @code
+
+@item MLError error()
+@pindex MLException.error
+
+Returns the underlying @code{MLError} value.
+
+@item string msg()
+@pindex MLException.msg
+
+Return a string describing the reason for the exception.
+
+@item this(string msg)
+@pindex MLException.this(string msg)
+
+Construct a new @code{MLException} by providing only an error message.
+
+@item this(MLError error)
+@pindex MLException.this(MLError error)
+
+Construct a new @code{MLException} by providing a @code{MLError} code.  The
+error message is determined by this value.
+
+@item this(string msg, MLError error)
+@pindex MLException.this(string msg, MLError error)
+
+Construct a new @code{MLException} by providing a custom message and error
+code.
 
 @end table
 
@@ -343,26 +436,28 @@ The format of @var{args} depends on what the @var{command} is.
 A simple example that demonstrates most aspects of the library.
 
 
-@verbatim
-// I (mio, <[e-mail]>) have release this example to the
+@example
+// I (mio, <stigma@@disroot.org>) have released this example to the
 // public domain. For more information, visit
 // <http://creativecommons.org/publicdomain/zero/1.0/>.
-import std.stdio;
+
+import std.stdio : stderr, writeln, writefln;
+import std.file : remove;
 
 import medialist;
 
 void print_error(MLError err)
-{
-  writefln("Error: MLError.%s", err);
-}
+@{
+  stderr.writefln("Error: MLError.%s", err);
+@}
 
 int main(string[] args)
-{
+@{
   if (2 > args.length)
-    {
+    @{
       stderr.writefln("usage: %s <path_to_list.tsv>", args[0]);
       return 1;
-    }
+    @}
 
   /* Open a new list for editing, creating the file if needed */
   MediaList* list = ml_open_list(args[1]);
@@ -370,6 +465,9 @@ int main(string[] args)
   /* Make sure the memory is returned when the program exits. */
   scope(exit) ml_free_list(list);
 
+  /* Since we don't want to keep the file for this example. */
+  scope(exit) remove(list.filePath);
+
   /* Error handling */
   MLError err;
 
@@ -380,18 +478,18 @@ int main(string[] args)
    * The second has default status (UNKNOWN).
    * The third has default progress (-/-).
    */
-  err = ml_send_command(list, MLCommand.add, ["Item 1"]);
+  ml_send_command(list, MLCommand.add, ["Item 1"], err);
   if (MLError.success != err) print_error(err);
 
-  err = ml_send_command(list, MLCommand.add, ["Item 2", "10/100"]);
+  ml_send_command(list, MLCommand.add, ["Item 2", "10/100"], err);
   if (MLError.success != err) print_error(err);
 
-  err = ml_send_command(list, MLCommand.add,
-                        ["Item 3", null, "PLAN-TO-WATCH"]);
+  ml_send_command(list, MLCommand.add, ["Item 3", null, "PLAN-TO-WATCH"],
+                  err);
   if (MLError.success != err) print_error(err);
 
-  err = ml_send_command(list, MLCommand.add,
-                        ["Item 4", "10/10", "COMPLETE"]);
+  ml_send_command(list, MLCommand.add, ["Item 4", "10/10", "COMPLETE"],
+                  err);
 
 
   /*
@@ -401,24 +499,24 @@ int main(string[] args)
    * We update the start date and end date of item 4.
    * We update the title of item 3.
    */
-  err = ml_send_command(list, MLCommand.update,
-                        ["1", "progress::0/100", "status::PLAN-TO-READ"]);
+  ml_send_command(list, MLCommand.update,
+                 ["1", "progress::0/100", "status::PLAN-TO-READ"], err);
   if (MLError.success != err) print_error(err);
 
-  err = ml_send_command(list, MLCommand.update,
-                        ["4", "start_date::2021-11-25",
-                         "end_date::2022-02-13"]);
+  ml_send_command(list, MLCommand.update,
+                  ["4", "start_date::2021-11-25", "end_date::2022-02-13"],
+                  err);
   if (MLError.success != err) print_error(err);
 
-  err = ml_send_command(list, MLCommand.update,
-                       ["3", "title::The Third Item"]);
+  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. */
-  MediaListItem item4 = ml_fetch_item(list, 4, &err);
+  MediaListItem item4 = ml_fetch_item(list, 4, err);
 
   if (MLError.success == err && true == item4.valid)
-    {
+    @{
       writeln("Details about item4:");
       writefln("Title:       %s", item4.title);
       writefln("Progress:    %s", item4.progress);
@@ -426,26 +524,23 @@ int main(string[] args)
       writefln("Start Date:  %s", item4.startDate);
       writefln("End Date:    %s", item4.endDate);
       writefln("Last Update: %s", item4.lastUpdated);
-    }
+    @}
   else
-    {
+    @{
       stderr.writefln("Failed to fetch item4: MLError.%s (Valid? %s)",
                       err, item4.valid ? "true" : "false");
-    }
+    @}
 
   /*
-   * Delete some items, then delete the list file.
+   * Delete some items.
    */
-  err = ml_send_command(list, MLCommand.delete_, ["3", "2"]);
-  if (MLError.success != err) print_error(err);
-
-  err = ml_send_command(list, MLCommand.delete_, []);
+  ml_send_command(list, MLCommand.delete_, ["3", "2"], err);
   if (MLError.success != err) print_error(err);
 
   /* Done ! */
   return 0;
-}
-@end verbatim
+@}
+@end example
 
 
 @node Index

--- a/medialist.d
+++ b/medialist.d
@@ -141,9 +141,6 @@ struct MediaListItem
     ///
     /// title, progress, status, start_date, end_date, last_updated.
     ///
-    /// Params:
-    ///   item = The MediaListItem to convert to a string
-    ///
     /// Returns: A string containing the TSV representation of *item*.
     ///
     string tsvRepresentation() const {
@@ -222,7 +219,7 @@ enum MLCommand
     ///
     /// If no there are no "Item ID" values in `args`, then the entire
     /// list is irreversibly deleted. **NOTE**: This functionality has
-    /// been deprecated from version 0.2.0, it'll be removed in a later
+    /// been deprecated from version 0.4, it'll be removed in a later
     /// version.
     ///
     delete_,
@@ -263,12 +260,12 @@ enum MLError
     itemNotFound,
     /// We don't have permission to edit the list file.
     permissionError,
-    /// Unknown error has occurred.
-    unspecifiedError,
     /// Unknown value sent to ml_send_command.
     ///
     /// Check all values in the `MLCommand` enumeration.
     unknownCommand,
+    /// Unknown error has occurred.
+    unspecifiedError,
 }
 
 private static string[] mlErrorStrings = [