{"id":18854360,"url":"https://github.com/urbanjost/m_cli2","last_synced_at":"2026-02-27T01:05:19.684Z","repository":{"id":38195678,"uuid":"284606381","full_name":"urbanjost/M_CLI2","owner":"urbanjost","description":"Fortran commandline-interface using a simple prototype command","archived":false,"fork":false,"pushed_at":"2025-06-21T14:29:42.000Z","size":39200,"stargazers_count":21,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-21T15:30:05.149Z","etag":null,"topics":["argument","command-line","fortran","fortran-package-manager","parsing"],"latest_commit_sha":null,"homepage":"","language":"Fortran","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urbanjost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-03T04:53:00.000Z","updated_at":"2025-06-21T14:29:45.000Z","dependencies_parsed_at":"2025-04-22T01:32:23.123Z","dependency_job_id":null,"html_url":"https://github.com/urbanjost/M_CLI2","commit_stats":{"total_commits":207,"total_committers":4,"mean_commits":51.75,"dds":0.04347826086956519,"last_synced_commit":"d893946bdd9a6b68865f18a4dab1258148b9325a"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/urbanjost/M_CLI2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbanjost%2FM_CLI2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbanjost%2FM_CLI2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbanjost%2FM_CLI2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbanjost%2FM_CLI2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urbanjost","download_url":"https://codeload.github.com/urbanjost/M_CLI2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbanjost%2FM_CLI2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263370189,"owners_count":23456428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argument","command-line","fortran","fortran-package-manager","parsing"],"created_at":"2024-11-08T03:47:58.189Z","updated_at":"2026-02-27T01:05:19.659Z","avatar_url":"https://github.com/urbanjost.png","language":"Fortran","funding_links":[],"categories":[],"sub_categories":[],"readme":"# M_CLI2.f90 and associated files\n![M_CLI2](docs/images/M_CLI2.gif)\n## Name\n### M_CLI2 - parse Unix-like command line arguments from Fortran\n\n## Description\n**M_CLI2**(3) is a Fortran module that will crack the command line when\ngiven a prototype string that looks very much like an invocation of\nthe program. Calls are then made for each parameter name to set \nvariables appropriately in the program.\n\nOne common style of use is to isolate all the parsing to the beginning\nof the program, which is generally just a few lines:\n```fortran\n   program compartmentalized\n   use M_CLI2, only : set_args, sget, rget, dget, iget, lget\n   implicit none\n     ! define command and default values and parse command line\n     call set_args('-x 1 -y 2.0 -i 11 --title:T \"my title\" -l F -L F', \u0026\n\n     ! optional block of text to display when the --help option appears\n     help_text=[character(len=80):: \u0026\n     'NAME', \u0026\n     '  compartmentalized - example program for parsing command line', \u0026\n     'DESCRIPTION', \u0026\n     '   A program to illustrate using M_CLI2 to parse the command line', \u0026\n     '   including creating help text using a block of text.', \u0026\n     'OPTIONS', \u0026\n     ' -x,-y:      some real values', \u0026\n     ' -i:         a whole number', \u0026\n     ' --title,T:  title line', \u0026\n     ' -l,-L       some Boolean options', \u0026\n     ''], \u0026\n\n     ! optional block of text to display when the --version option appears\n     version_text=[character(len=80):: \u0026\n     'PROGRAM:     compartmentalized               ', \u0026\n     'DESCRIPTION: Illustrate command line parsing ', \u0026\n     'VERSION:     1.0, 2026-01-26                 ', \u0026\n     'AUTHOR:      Leonardo DaVinci                ', \u0026\n     'LICENSE:     Public Domain', \u0026\n     ''])\n\n     ! get all the argument values and assign them to variables of various\n     ! types \n     call main(\u0026\n     \u0026 x=rget('x'), y=rget('y'), \u0026 ! get some float values\n     \u0026 title=sget('title'),      \u0026 ! get a string\n     \u0026 i=iget('i'),              \u0026 ! get a whole number\n     l=lget('l'), lbig=lget('L'))  ! get some boolean options\n   contains\n\n   subroutine main(x,y,title,i,l,lbig)\n   ! do something with the values, all the parsing is done\n   real                          :: x,y     ;namelist /args/x,y\n   logical                       :: l,lbig  ;namelist /args/l,lbig\n   integer                       :: i       ;namelist /args/i\n   character(len=:),allocatable  :: title   ;namelist /args/title\n   write(*,nml=args)\n   end subroutine main\n\n   end program compartmentalized\n```\n## General Overview\n\nThe **SET_ARGS(3)** call defines the command options and default values\nand parses the command line. The common Unix command line style is\nsupported where \"--keyword=value\" or \"--keyword value\" for long names\n(multiple character) and \"-L\" for short names (where L is a single\nletter).\n\nThe \"\\*GET\" routines are all that is required to assign scalar values from\nthe command line values by keyword to Fortran variables.\n\nAdditionally, the matching \"\\*GETS\" functions return arrays of values.\n\nYou can query whether a keyword has been specified or not using\n**SPECIFIED**(3). \n\n**M_CLI2**(3) intentionally does not include validating values beyond\ntype because Fortran is already very good at that. The example program\nin the document for\n[**SPECIFIED**(3)](example/demos/demo_specified.f90)\nshows how to determine if required parameters are present, to ensure\nonly one of a number of mutually exclusive options has been chosen,\nthat a value matches a specified range or is a member of a given set, ...\n\nAs illustrated, text blocks to display when --help or --version\nis supplied on the command line can optionally be added to the\n**SET_ARGS**(3) call.\n\nA few additional modes are also available. For example, by default\nBoolean short names may not be concatenated, but in \"strict\" mode they\ncan be (but in \"strict\" mode then long keywords must always start with\ntwo dashes instead of one or two being allowed).\n\nThere are also advanced features such as support for \"response files\"\nwhich let you create platform-independent aliases for long commands,\nsupport for subcommands, and a few other less-used capabilities.\n\nAll the features are demonstrated via example programs and man-page\nformat descriptions of each procedure.\n\nAn arbitrary number of strings such as filenames may be passed in on\nthe end of commands; and **get_args**(3)-related routines can be used for\nrefining options such as requiring lists of a specified size.\n\nNote that these parameters are defined automatically\n```bash\n    --help\n    --usage\n    --verbose\n    --version\n```\nWhere you supply text for the optional \"--help\" and \"--version\" keywords, as\ndescribed under **SET_ARGS**(3).\n\n## More specifically ...\n\n## Syntax rules for the prototype command in **SET_ARGS**(3):\n\n  The syntax used in **SET_ARGS**(3) is similar to invoking the command\n  from the command using just a few simple rules:\n\n   + Each keyword must have a default value specified separated from\n     the keyword by a space.\n   + double-quote string values\n   + use a value of F unquoted to designate a keyword as Boolean\n   + to have both a long and short keyword name designate the long\n     name followed immediately by \":LETTER\" where LETTER is the short\n     keyword name.\n   + separate lists of values with commas\n   + if the value can start with a dash and you want to allow the\n     syntax \"--keyword value\" add a : to the end of the keyword, which\n     means \"next argument is a value even if it starts with \" -\".\n\n### Example call to **SET_ARGS**(3):\n```bash\n    call set_args('-a -10 -b 1,2,3 --title:T \"my title\" -t F')\n```\n  That single line defines all the command keywords and their default values\n  and parses the command line.\n\n## Getting keyword values\n\n  All that remains is to get argument values. To get the values\n* you add calls to the **get_args**(3) subroutine or one of its shortcut\n  function names.\n\n  These alternative shortcut names are convenience procedures\n  (**rget**(3),**sget**(3),**iget**(3) ...) that allow you to use a simple\n  function-based interface.\n\n  Less frequently used are special routines for when you want to use\n  fixed length **CHARACTER** variables or fixed-size arrays instead of\n  the allocatable variables. These require routines that start with\n  \"GET_ARGS\".\n\n## That is usually it\n\n  Now when you call the program all the values in the program should\n  be updated using values from the prototype and command line and be\n  ready to use in your program.\n\n![demos](docs/images/demo.gif)\n## Demo Programs\nThese demo programs provide templates for the most common usage:\n\n* [demo3](example/demo3.f90)   Example of **basic** use\n* [demo1](example/demo1.f90)   Using the convenience functions\n* [demo9](example/demo9.f90)   Long and short names using --LONGNAME:SHORTNAME.\n* [demo2](example/demo2.f90)   Putting everything including **help** and **version** information into a contained procedure.\n* [demo17](example/demo17.f90) Using unnamed options as filenames or strings\n* [demo16](example/demo16.f90) Using unnamed values as numbers\n\n## Optional Modes\n* [demo15](example/demo15.f90) Allowing bundling short Boolean keys using \"strict\" mode\n* [demo14](example/demo14.f90) Optional mode for case-insensitive long keys\n* [demo12](example/demo12.f90) Enabling response files\n* [demo13](example/demo13.f90) Mode for equivalencing dash to underscore in keynames\n\n## Niche examples\n* [demo8](example/demo8.f90)   Parsing multiple keywords in a single call to **get_args**(3)\n* [demo4](example/demo4.f90)   **COMPLEX**-type values\n* [demo7](example/demo7.f90)   Controlling delimiter characters for values that are arrays\n* [demo6](example/demo6.f90)   How to create a command with subcommands\n* [demo5](example/demo5.f90)   extended description of using _CHARACTER_ type values\n\n## Response files\n[Response files](response.md) are supported as described in the documentation for\n[set_args](https://urbanjost.github.io/M_CLI2/set_args.3m_cli2.html).\nThey are a system-independent way to create short abbreviations for long\ncomplex commands. This option is generally not needed by programs with\njust a few options, but can be particularly useful for programs with\ndozens of options where various values are frequently reused.\n\n![docs](docs/images/docs.gif)\n## Documentation\n\n![manpages](docs/images/manpages.gif)\n### man-pages\n- HTML [man-pages](https://urbanjost.github.io/M_CLI2/man3.html) index of individual procedures\n- HTML [book-form ](https://urbanjost.github.io/M_CLI2/BOOK_M_CLI2.html) of pages consolidated using JavaScript\n+ [manpages.zip](https://urbanjost.github.io/M_CLI2/manpages.zip) for installing wherever the man(1) command is available\n+ [manpages.tgz](https://urbanjost.github.io/M_CLI2/manpages.tgz) is an alternative tar(1) format archive\n\n### developer documentation\n- [doxygen(1) output](https://urbanjost.github.io/M_CLI2/doxygen_out/html/index.html).\n- [ford(1) output](https://urbanjost.github.io/M_CLI2/fpm-ford/index.html).\n\n### logs\n- [CHANGELOG](docs/CHANGELOG.md)\n- [STATUS](docs/STATUS.md) of most recent CI/CD runs\n\n### standalone command-line documentation program\nThe\n[3.2.0 release](https://github.com/urbanjost/M_CLI2/releases/tag/V3.2.0)\nof the command-line parser module\n[M_CLI2](https://github.com/urbanjost/M_CLI2)\nhas a [standalone program](https://raw.githubusercontent.com/urbanjost/index/main/bootstrap/fpm-m_cli2.f90)\navailable that will display the help text for the procedures as a\nsubstitute for the man(1) pages.\n\nIf the program is placed in your search path you can enter\n```text\nfpm-m_cli2 --help\n# if an fpm user\nfpm m_cli2 --help\n```\nfor a description of usage.\nAn example to build it on a typical Linux platform would be\n```bash\n# create a scratch directory for the build\nmkdir temp\ncd temp\n# get the documentation program\ncurl https://raw.githubusercontent.com/urbanjost/index/main/bootstrap/fpm-m_cli2.f90\n# compile the program\ngfortran fpm-m_cli2.f90 -o fpm-m_cli2\n# copy it to somewhere in your path\nmv fpm-m_cli2 $HOME/.local/bin/\n```\n\n![gmake](docs/images/gnu.gif)\n## Download and Build with Make(1)\n   Compile the **M_CLI2** module and build all the example programs.\n```bash\n   git clone https://github.com/urbanjost/M_CLI2.git\n   cd M_CLI2/src\n   # change Makefile if not using one of the listed compilers\n\n   # for gfortran\n   make clean\n   make gfortran\n\n   # for ifort\n   make clean\n   make ifort\n\n   # for nvfortran\n   make clean\n   make nvfortran\n\n   # display other options (test, run, doxygen, ford, ...)\n   make help\n```\n   To install you then generally copy the *.mod file and *.a file to\n   an appropriate directory.  Unfortunately, the specifics vary but in\n   general if you have a directory $HOME/.local/lib and copy those files\n   there then you can generally enter something like\n```bash\n     gfortran -L$HOME/.local/lib -lM_CLI2  myprogram.f90 -o myprogram\n```\n   There are different methods for adding the directory to your default\n   load path, but frequently you can append the directory you have\n   placed the files in into the colon-separated list of directories\n   in the **$LD_LIBRARY_PATH** or **$LIBRARY_PATH** environment variable, and\n   then the -L option will not be required (or it's equivalent in your\n   programming environment).\n```bash\n       export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH\n```\n   **NOTE**: If you use multiple Fortran compilers you may need to create\n   a different directory for each compiler. I would recommend it, such\n   as $HOME/.local/lib/gfortran/.\n\n### Creating a shared library\n\n   If you desire a shared library as well, for gfortran you may enter\n```bash\n     make clean gfortran gfortran_install\n```\n   and everything needed by gfortran will be placed in libgfortran/ that\n   you may add to an appropriate area, such as $HOME/.local/lib/gfortran/.\n```bash\n     make clean ifort ifort_install # same for ifort\n```\n   does the same for the ifort compiler and places the output in libifort/.\n### Specifics may vary\n\n   NOTE: The build instructions above are specific to a ULS (Unix-Like\n   System) and may differ, especially for those wishing to generate shared\n   libraries (which varies significantly depending on the programming\n   environment). For some builds it is simpler to make a Makefile for\n   each compiler, which might be required for a more comprehensive build\n   unless you are very familiar with gmake(1).\n\n   If you always use one compiler it is relatively simple, otherwise\n   make sure you know what your system requires and change the Makefile\n   as appropriate.\n\n![parse](docs/images/fpm_logo.gif)\n## Build with FPM\n   Alternatively, fpm(1) users may download the github repository and build it with\n   fpm ( as described at [Fortran Package Manager](https://github.com/fortran-lang/fpm) )\n```bash\n        git clone https://github.com/urbanjost/M_CLI2.git\n        cd M_CLI2\n        fpm test   # build and test the module\n        fpm install # install the module (in the default location)\n```\n   or just list it as a dependency in your fpm.toml project file.\n```toml\n        [dependencies]\n        M_CLI2        = { git = \"https://github.com/urbanjost/M_CLI2.git\" }\n```\n---\n![cmake](docs/images/cmake_logo-1.png)\n---\n## Download and Build using cmake\n\nTo download the github repository and build and install with cmake\n(you may wish to change the install path in src/CMakeLists.txt first) :\n```bash\n      git clone https://github.com/urbanjost/M_CLI2.git\n      cd M_CLI2\n\n      # Create a Build Directory:\n      mkdir -p build\n\n      cd build\n      cmake -S ../src -B .\n\n      # Configure the Build, specifying your preferred compiler (ifort, flang, etc.):\n      cmake . -DCMAKE_Fortran_COMPILER=gfortran\n\n      # Build the Project:\n      cmake --build .\n\n      #This creates:\n      #\n      #    build/lib/libM_CLI2.a (the static library).\n      #    build/include/*.mod (module files).\n      #    build/test/* (test executables).\n      #    build/example/* (example executables).\n\n      # OPTIONAL SECTION:\n\n      # Verify build\n      ls build/lib/libM_CLI2.a\n      ls build/include/*.mod\n      ls build/test/*\n      ls build/example/*\n\n      #Optionally Run Tests and Examples:\n      for name in ./test/* ./example/*\n      do\n         $name\n      done\n\n      #Install (Optional):\n      # This installs the library and module files to the system\n      # (e.g., /usr/local/lib/ and /usr/local/include/).\n      cmake --install .\n\n      # if you have insufficient permissions sudo(1) may be required\n      # to perform the install\n      #sudo cmake --install .\n\n      # Verify installation\n      ls /usr/local/lib/libM_CLI2.a\n      ls /usr/local/include/*.mod\n\n      # Cleaning Up: To clean artifacts, remove the build/ directory:\n      rm -rf build\n```\n\n## Supports Meson\n   Alternatively, meson(1) users may download the github repository and build it with\n   meson ( as described at [Meson Build System](https://mesonbuild.com/) )\n```bash\n        git clone https://github.com/urbanjost/M_CLI2.git\n        cd M_CLI2\n        meson setup _build\n        meson test -C _build  # build and test the module\n\n        # install the module (in the \u003cDIR\u003e location)\n        # --destdir is only on newer versions of meson\n        meson install -C _build --destdir \u003cDIR\u003e\n        # older method if --destdir is not available\n        env DESTDIR=\u003cDIR\u003e meson install -C _build\n```\n   or just list it as a [subproject dependency](https://mesonbuild.com/Subprojects.html) in your meson.build project file.\n```meson\n        M_CLI2_dep = subproject('M_CLI2').get_variable('M_CLI2_dep')\n```\n\n\n## Commit Tests ##\n\ncommit `598e44164eee383b8a0775aa75b7d1bb100481c3` was tested on 2020-11-22 with\n + GNU Fortran (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5)\n + ifort (IFORT) 19.1.3.304 20200925\n + nvfortran 20.7-0 LLVM 64-bit target on x86-64 Linux\n\n\ncommit `8fe841d8c0c1867f88847e24009a76a98484b31a` was tested on 2021-09-29 with\n + GNU Fortran (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0\n + ifort (IFORT) 2021.3.0 20210609\n + nvfortran 21.5-0 LLVM 64-bit target on x86-64 Linux -tp nehalem\n\ncommit `732bcadf95e753ccdf025cec2c08d776ea2534c2` was tested on 2023-02-10 with\n + ifort (IFORT) 2021.8.0 20221119\n + GNU Fortran (Ubuntu 11.1.0-1ubuntu1~20.04) 11.1.0\n---\n\u003c!--\nLast updated:   Wed Sep 29 17:34:52 2021 -0400\nLast update: Sat 21 Jan 2023 11:10:53 PM EST\n--\u003e\nLast update: Saturday, February 4th, 2023 1:12:54 AM UTC-05:00\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbanjost%2Fm_cli2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furbanjost%2Fm_cli2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbanjost%2Fm_cli2/lists"}