WFOPT.NET 0.1.0

About

The Wheefun Options Parsing Library for .NET (WFOPT.NET) ports functionality from the C implementation of WFOPT to the .NET runtime.

Rationale

Option parsing is a common requirement for command-line interface (CLI) programs, which sometimes need these options to run in batch to parameterize execution. There are many different ways of doing so which vary between operating system and programming language; for instance, the GNU Getopt library is commonly used by programs written for UNIX and in the C programming language.

Unfortunately, this can make writing portable CLI programs difficult. GNU Getopt is one possible solution and is somewhat of an informal standard in UNIX-like programs; however, there may be good reasons to not use this solution, including the fact that the Windows ecosystem uses an entirely different convention for command-line arguments. In some cases, there may not be a good option for implementing command-line arguments for a given environment at all, forcing the user to roll their own implementation of command-line parsing.

WFOPT was originally developed in C and aims to solve two primary issues. First, it allows users who just want some form of argument parsing in their program to implement that. WFOPT provides several option parsers so that client code can utilize the most appropriate one for its purposes; it also uses the MVC pattern while parsing options so that the parser, option set, and results are modular. Users utilizing WFOPT may bind both argument validation and callbacks to options, allowing for WFOPT to be robust in the face of many use cases.

Secondly, WFOPT provides a framework which allows minimal effort to be required when writing a new option parser de novo. The task of a parser in WFOPT is to interpret the option set given to it and (via processing the input arguments) binding matches to a result set. WFOPT already provides the machinery needed for the option set and the result set, so all a parser needs to do is interpret the input arguments. Convenience classes exist to assist in this effort.

WFOPT.NET is a port of WFOPT for the .NET runtime. There are other option parsing libraries available for .NET runtime (such as GNU.Getopt, Heyes.GetOpt, and Mono.Options), so if nothing else, WFOPT.NET adds another option to the list. However, the advantages of WFOPT make it particularly well suited to option parsing, and it is hoped that it will be useful to others.

License

WFOPT.NET is licensed under the GNU GPL version 3 with the Classpath Exception. This was chosen so that changes to WFOPT.NET come back upstream, but also so that users who do not intend to modify WFOPT.NET can link against it without any concerns respecting its licensing. These users may do so without fear of the GPLv3 also applying to their (potentially proprietary) code just as long as a written offer for the source code is included with the binary, which may be satisfied by notifying the people who receive the binary that the WFOPT.NET source code is avaialble from one of the below websites. When they download it from here or from NuGet, they will receive a copy of the license.

A layman's version of the above is as follows: if you link against WFOPT.NET, notify your users that the source code is available. If you modify code that comes with WFOPT.NET and then later link a recompiled version of it into your program, you will need to make the changes to the WFOPT.NET code available. Your code will not otherwise be covered by the license.

Website

More information about the WFOPT.NET project may be found at the WFOPT.NET website; to obtain bindings for other execution environments, please see the website for the entire project.

Changelog

• 0.1.0 - Initial Release

Supported Languages

The listed versions of these programming languages are guaranteed to be supported by WFOPT.NET:

• Any language targeting the .NET 6.0 runtime

Other languages may be supported indirectly through one of these interfaces. WFOPT.NET itself is written in C#, but due to the nature of the CLR, supporting other languages is trivial.

Bindings also exist for other execution environments, though these are not directly supported by WFOPT.NET. As previously mentioned above, a native C implementation exists, but this library has also been ported to the Java programming langauge.

Supported Operating Systems

Any operating system which supports .NET runtime should generally also support WFOPT.NET, although it has only been tested on the Microsoft implementation of it. Support for Mono or other implementations of .NET has not been confirmed at this time. There is little in the way of platform-specific code in WFOPT.NET that will create issues, and it is written to be platform-independent.

Installation

Installation generally occurs through one of two mechanisms: through source code compilation, or through the NuGet Package Manager. The NuGet package manager is the most straightforward way to include WFOPT in your program: just add WFOPT.NET to your list of NuGet dependencies.

Compiling From Source

Alternatively, you may download WFOPT.NET from the above website to compile it from source. WFOPT.NET does't have any external dependencies, but it does require a .NET-aware IDE such as Visual Studio 2022. It also requires .NET 10 to build.

To obtain the source code, a Subversion client is required. You may use the GUI tools that come with TortiseSVN, or you may use the command line tools from it or another package. To do so, open up a terminal (like cmd.exe on Windows) and type the following:

svn co https://svn.code.sf.net/p/wfopt/net/code/trunk/ wfopt.net

Building within Visual Studio requires little effort; simply load the project, and select "Build Solution" from the Build Menu (alternately, Ctrl-Shift-B). To build from command, start a developer console and type the following:

> cd <project-root>/WFOPT
> MSBuild

Installing the NuGet Package into a local repository

The easiest way to integrate the package into your build environment is to add it to a local NuGet repository. If you have not set this up, you can add the output directory directly (it is located at <project-root>/WFOPT/WFOPT/bin/Debug/) or you can create a repository directory where you can place many packages. Assuming that the package is located in <package-source>, you can add it using the following:

> dotnet nuget add source -n "Local Repo" <package-source>

Alternatively, you can add it using Tools → NuGet Package Manager → Package Manager Settings → Package Sources. Occasionally, the NuGet cache will become stale if any development is done on WFOPT and it will need to be removed from the local cache. You can use the following commands WFOPT from the local NuGet cache on Windows and UNIX systems respectively:

> rd /S /Q %UserProfile%\.nuget\packages\wfopt

$ rm -r ~/.nuget/packages/wfopt

For convenience, the "purge-nuget.bat" and "purge-nuget.sh" scripts have been added to the source distribution for Windows and UNIX systems respectively. These scripts will automatically remove any WFOPT.NET assets in NuGet's cache and can be conveniently executed from a GUI environment. Every effort will be made to ensure that official releases do not have this caveat.

Including WFOPT.NET via NuGet

With the new source available (or when the package is in the main NuGet repository), you can include WFOPT.NET into your own code by either right clicking on the project and clicking "Manage NuGet Packages", then installing WFOPT.NET, or by adding the following to your project file:

<ItemGroup>
	<PackageReference Include="WFOPT" Version="0.1.0" />
</ItemGroup>

Note that if you are working from a local NuGet repository, the .snuget package that provides debugging symbols may not be pulled along with it. This is a known bug in the NuGet packagine of WFOPT.NET and for now, the best option seems to be to copy the PDB file from bin\Debug\net6.0 to the corresponding bin directory of your program.