optslib/README.md

# OptsLib

A basic Options parser and command-line arguments handling a library for PHP.

## Table of Contents

<!-- TOC -->
* [OptsLib](#optslib)
  * [Table of Contents](#table-of-contents)
  * [Installation](#installation)
  * [Compiling from source](#compiling-from-source)
  * [Testing](#testing)
  * [Usage](#usage)
    * [parseArgument()](#parseargument)
    * [getArguments()](#getarguments)
  * [Additional functionality](#additional-functionality)
    * [getRegex()](#getregex)
    * [setRegex()](#setregex)
  * [Changelog](#changelog)
  * [License](#license)
  * [Logo](#logo)
  * [Contributing](#contributing)
<!-- TOC -->

## Installation

The library can be installed using ncc:

```bash
# n64
ncc package install -p "nosial/libs.opts=latest@n64"

# github
ncc package install -p "nosial/libs.opts=latest@github"
```

or by adding the following to your project.json file under
the `build.dependencies` section:

```json
{
  "name": "net.nosial.optslib",
  "version": "latest",
  "source_type": "remote",
  "source": "nosial/libs.opts=latest@n64"
}
```

If you don't have the n64 source configured you can add it
by running the following command:

```bash
ncc repository add --name n64 --type gitlab --host git.n64.cc
```

## Compiling from source

The library can be compiled from source using ncc:

```bash
ncc build --config release
```

or by running the following command:

```bash
make release
```

## Testing

The library can be tested using PhpUnit with the `phpunit.xml` file that is already included in the repository.
This requires that you have PhpUnit installed & the library has been compiled and installed on the local system.

```bash
phpunit
```


## Usage

The usage of this library is very simple, there are
two functions that you can use to parse options.

### parseArgument()

Can be used to parse a single argument string/array, this is useful for
parsing command line arguments. The second argument is the maximum number
of arguments that can be parsed, this is to prevent infinite loops.

```php
<?php

    require_once('ncc');
    import('net.nosial.optslib', 'latest');
    
    $input = '--foo --bar="test" -y --username test';
    $parsed = \OptsLib\Parse::parseArgument($input);
    
    echo $parsed['foo']; // true
    echo $parsed['bar']; // "test"
    echo $parsed['y']; // true
    echo $parsed['username']; // "test"
```

### getArguments()

This method is used to access the `$argv` array
if it's not set, an empty array is returned.

```php
<?php

    require_once('ncc');
    import('net.nosial.optslib', 'latest');
    
    $arguments = \OptsLib\Parse::getArguments();
    
    echo $arguments['output-file']; // "test.txt"
    echo $arguments['input-file']; // "test.txt"
    echo $arguments['log']; // "verbose"
```

Optionally, if you want arguments after a specific argument/option
to be parsed, you can pass the argument name as the first argument.

This is ideal if you are using a command line tool that has
a sub-command, for example:

```bash
$ mytool subcommand --foo --bar="test" -y --username test
```

In this case, you can pass the `subcommand` argument to the
`getArguments()` method to parse the arguments after it.

```php
<?php

    require_once('ncc');
    import('net.nosial.optslib', 'latest');
    
    $arguments = \OptsLib\Parse::getArguments('subcommand');
    
    echo $arguments['foo']; // true
    echo $arguments['bar']; // "test"
    echo $arguments['y']; // true
    echo $arguments['username']; // "test"
```

## Additional functionality

OptsLib also provides some additional functionality that
can be used to modify the way arguments are parsed.

### getRegex()

This method is used to return the regex pattern used to parse
the arguments, it can be used to parse arguments manually.

The default used is

```regexp
/(?(?=-)-(?(?=-)-(?'bigflag'[^\\s=]+)|(?'smallflag'\\S))(?:\\s*=\\s*|\\s+)(?(?!-)(?(?=[\\\"\\'])((?<![\\\\])['\"])(?'string'(?:.(?!(?<![\\\\])\\3))*.?)\\3|(?'value'\\S+)))(?:\\s+)?|(?'unmatched'\\S+))/
```

### setRegex()

This method is used to set the regex pattern used to parse
the arguments, you can modify the default pattern to suit your needs.

```php
<?php

    require_once('ncc');
    import('net.nosial.optslib', 'latest');
    
    \OptsLib\Parse::setRegex('/(?(?=-)-(?(?=-)-(?'bigflag'[^\\s=]+)|(?'smallflag'\\S))(?:\\s*=\\s*|\\s+)(?(?!-)(?(?=[\\\"\\'])((?<![\\\\])['\"])(?'string'(?:.(?!(?<![\\\\])\\3))*.?)\\3|(?'value'\\S+)))(?:\\s+)?|(?'unmatched'\\S+))/');
```


## Changelog

For a list of changes, see the [CHANGELOG.md](CHANGELOG.md) file.


## License

This library is licensed under the MIT license, see the LICENSE file
for more information.


## Logo

The logo was created by [Boxicons](https://boxicons.com/) and is licensed
under the [MIT license](assets/LICENSE)

## Contributing

If you want to contribute to this project, you can do so by
creating a merge request on the [GitLab repository](https://git.n64.cc/nosial/libs/optslib).