Metadata-Version: 2.1
Name: libdash
Version: 0.3
Summary: Bindings for the dash shell as a library
Author-email: Michael Greenberg <michael@greenberg.science>
License: Copyright (c) 1989-1994
        	The Regents of the University of California.  All rights reserved.
        Copyright (c) 1997 Christos Zoulas.  All rights reserved.
        Copyright (c) 1997-2005
        	Herbert Xu <herbert@gondor.apana.org.au>.  All rights reserved.        
        This code is derived from software contributed to Berkeley by Kenneth Almquist.                
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions
        are met:
        1. Redistributions of source code must retain the above copyright
           notice, this list of conditions and the following disclaimer.
        2. Redistributions in binary form must reproduce the above copyright
           notice, this list of conditions and the following disclaimer in the
           documentation and/or other materials provided with the distribution.
        3. Neither the name of the University nor the names of its contributors
           may be used to endorse or promote products derived from this software
           without specific prior written permission.        
        THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
        OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
        OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
        SUCH DAMAGE.        
        mksignames.c:        
        This file is not directly linked with dash.  However, its output is.        
        Copyright (C) 1992 Free Software Foundation, Inc.        
        This file is part of GNU Bash, the Bourne Again SHell.        
        Bash is free software; you can redistribute it and/or modify it under
        the terms of the GNU General Public License as published by the Free
        Software Foundation; either version 2, or (at your option) any later
        version.        
        Bash is distributed in the hope that it will be useful, but WITHOUT ANY
        WARRANTY; without even the implied warranty of MERCHANTABILITY or
        FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
        for more details.        
        You should have received a copy of the GNU General Public License with
        your Debian GNU/Linux system, in /usr/share/common-licenses/GPL, or with the
        Debian GNU/Linux hello source package as the file COPYING.  If not,
        write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
        Boston, MA 02111 USA.        
Project-URL: Homepage, https://github.com/mgree/libdash
Project-URL: Bug Tracker, https://github.com/mgree/libdash/issues
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: System Shells
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Requires-Python: >=3.7
Description-Content-Type: text/markdown

[![Main workflow](https://github.com/mgree/libdash/actions/workflows/build.yml/badge.svg)](https://github.com/mgree/libdash/actions/workflows/build.yml)

*libdash* is a fork of the Linux Kernel's `dash` shell that builds a linkable library with extra exposed interfaces. The primary use of libdash is to parse shell scripts, but it could be used for more.

The Python bindings are packaged as the [`libdash` PyPi package](https://pypi.org/project/libdash/).

The OCaml bindings---packaged as the [`libdash` OPAM package](https://opam.ocaml.org/packages/libdash/)---include two executables, `shell_to_json` and `json_to_shell`, which let you conveniently parse POSIX shell scripts into a JSON AST.

# What are the dependencies?

The C code for dash should build on a wide variety of systems; it requires `libtool` and `autotools` (`aclocal`, `autoheader`, `automake`, `autoconf`). The library may not build on platforms with esoteric linkers; it's been tested on macOS and Linux.

The Python and OCaml bindings depend on being able to build the C code. See `libdash.opam` for details on the OCaml code's dependencies, which includes the build-time external dependencies. Python wheels have no need for these build-time dependencies, but building from a Python source distribution will only succeed when `libtool` and `autotools` are present.

The CI scripts (in `.github/workflows/build.yml`) give build details.

## How to build `libdash` from source

### Python

Run `python3 setup.py install`. On macOS, you must first install the build dependencies via `brew install libtool autoconf automake`.

You can test the Python bindings by running:

```
cd python; make test
```

### OCaml

Install the OPAM file: `opam pin add .` or `opam install .`. This will build the OCaml library and install it in your OPAM repository. There are tests in another directory; they will only build when libdash is actually installed.

You can test the OCaml bindings by running:

```
cd ocaml; make test
```

### Testing

The tests use `test/round_trip.sh` to ensure that every tester file in `test/tests` round-trips correctly through parsing and pretty printing.

Additionally, you can run tests that compare the OCaml and Python implementations (after you've installed them both):

```
cd test; make
```

# How to use the parser

For Python, see [`python/rt.py`](https://github.com/mgree/libdash/blob/master/python/rt.py), an example tool that does a round-trip: shell syntax to AST back to shell syntax.

For OCaml, see [`ocaml/shell_to_json.ml`](https://github.com/mgree/libdash/blob/master/ocaml/shell_to_json.ml), a tool that parses shell syntax and produces JSON (using the [atdgen](https://opam.ocaml.org/packages/atdgen/) bindings).

The ideal low-level interface to use is `parsecmd_safe` in `parser.c`; you'll need to ensure that dash's initialization routines have been called and that the stack marks are managed correctly. Parsing the POSIX shell is a complicated affair: beyond the usual locale issues, aliases affect the lexer, so one must use `setalias` and `unalias` to manage any aliases that ought to exist.

# How work with the parsed nodes

The general AST is described in `nodes.h`. There are some tricky invariants around the precise formatting of control codes; the OCaml code shows some examples of working with the `args` fields in `ocaml/ast.ml`, which converts the C AST to an OCaml AST.

The OCaml tools `shell_to_json` and `json_to_shell` will produce JSON ASTs, allowing you to work with these ASTs in any language.
