libdash 0.3__tar.gz → 0.4.0__tar.gz

libdash-0.4.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.1
+Name: libdash
+Version: 0.4.0
+Summary: Bindings for the dash shell as a library
+Author: PaSh contributors
+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/binpash/libdash
+Project-URL: Bug Tracker, https://github.com/binpash/libdash/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: System Shells
+Classifier: Operating System :: POSIX
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: COPYING
+
+[![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.
+
+# Pretty printing
+
+The pretty printer does its best to produce valid shell scripts, but it's possible to manually construct AST nodes that don't directly correspond to valid scripts.
+
+For example, the Python AST `[[['Q', [['C', 34]]]]]` represents a quoted field containing a double quote character. Translated literally, this would yield the string `"""`, which is not a valid shell script. The pretty printer will instead automatically escape the inner quote, rendering `"\""`.
+
+While the printer tries to get things right either way, you should use escapes to signal to the printer when to escape: you should use the Python AST `[[['Q', [['E', 34]]]]]` to mark the inner double quote as escaped.
+
+# Known issues
+
+We currently do not escape the character `!` (exclamation point). In an interactive shell, `!` is likely treated as a history substitution (and so should be escaped), but in a non-interactive shell, `!` is treated normally. We currently cater to non-interactive shells; eventually this behavior will be controllable.

{libdash-0.3 → libdash-0.4.0}/README.md

@@ -59,3 +59,15 @@ The ideal low-level interface to use is `parsecmd_safe` in `parser.c`; you'll ne
 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.
+
+# Pretty printing
+
+The pretty printer does its best to produce valid shell scripts, but it's possible to manually construct AST nodes that don't directly correspond to valid scripts.
+
+For example, the Python AST `[[['Q', [['C', 34]]]]]` represents a quoted field containing a double quote character. Translated literally, this would yield the string `"""`, which is not a valid shell script. The pretty printer will instead automatically escape the inner quote, rendering `"\""`.
+
+While the printer tries to get things right either way, you should use escapes to signal to the printer when to escape: you should use the Python AST `[[['Q', [['E', 34]]]]]` to mark the inner double quote as escaped.
+
+# Known issues
+
+We currently do not escape the character `!` (exclamation point). In an interactive shell, `!` is likely treated as a history substitution (and so should be escaped), but in a non-interactive shell, `!` is treated normally. We currently cater to non-interactive shells; eventually this behavior will be controllable.

{libdash-0.3 → libdash-0.4.0}/configure.ac

@@ -1,4 +1,4 @@
-AC_INIT([dash],[0.5.11.5])
+AC_INIT([dash],[0.5.13.3])
 AM_INIT_AUTOMAKE([foreign subdir-objects])
 AC_CONFIG_SRCDIR([src/main.c])
 AC_CONFIG_HEADERS(config.h)
@@ -10,10 +10,12 @@ dnl Checks for programs.
 AC_PROG_CC
 AC_USE_SYSTEM_EXTENSIONS
 
+dnl AC_GNU_SOURCE
 AC_PROG_YACC
 dnl MMG 2018-09-26 support building the library
 AM_PROG_AR
 
+
 AC_MSG_CHECKING([for build system compiler])
 if test "$cross_compiling" = yes; then
 	CC_FOR_BUILD=${CC_FOR_BUILD-cc}
@@ -38,17 +40,20 @@ fi
 AC_ARG_ENABLE(static, AS_HELP_STRING(--enable-static, \
 				     [Build statical linked program]))
 if test "$enable_static" = "yes"; then
-	export LDFLAGS="-static -Wl,--fatal-warnings"
+	export LDFLAGS="-static"
 fi
 
 AC_ARG_ENABLE(fnmatch, AS_HELP_STRING(--enable-fnmatch, \
 				      [Use fnmatch(3) from libc]))
 AC_ARG_ENABLE(glob, AS_HELP_STRING(--enable-glob, [Use glob(3) from libc]))
+AC_ARG_ENABLE(tee, AS_HELP_STRING(--disable-tee, [Do not use tee(2)]))
+AC_ARG_ENABLE(memfd_create, AS_HELP_STRING(--disable-memfd-create,
+					   [Do not use memfd_create(3)]))
 
 dnl Checks for libraries.
 
 dnl Checks for header files.
-AC_CHECK_HEADERS(alloca.h paths.h)
+AC_CHECK_HEADERS(alloca.h paths.h sys/wait.h)
 
 dnl Check for declarations
 AC_CHECK_DECL([_PATH_BSHELL],,AC_DEFINE_UNQUOTED([_PATH_BSHELL], "/bin/sh", [Define to system shell path]),[
@@ -91,9 +96,9 @@ AC_CHECK_DECL([PRIdMAX],,
 
 dnl Checks for library functions.
 AC_CHECK_FUNCS(bsearch faccessat getpwnam getrlimit isalpha killpg \
-	       mempcpy \
+	       memfd_create memrchr mempcpy \
 	       sigsetmask stpcpy strchrnul strsignal strtod strtoimax \
-	       strtoumax sysconf)
+	       strtoumax sysconf tee wait3)
 
 dnl Check whether it's worth working around FreeBSD PR kern/125009.
 dnl The traditional behavior of access/faccessat is crazy, but
@@ -135,6 +140,24 @@ if test "$use_fnmatch" = yes && test "$enable_glob" = yes; then
 	AC_CHECK_FUNCS(glob)
 fi
 
+if test "$enable_tee" != no; then
+	AC_CHECK_FUNCS(tee, use_tee=yes)
+fi
+
+if test "$use_tee" = yes; then
+	AC_DEFINE([USE_TEE], [1], [Non-zero if tee(2) should be used])
+else
+	AC_DEFINE([USE_TEE], [0], [Non-zero if tee(2) should be used])
+fi
+
+if test "$enable_memfd_create" != no; then
+	AC_DEFINE([USE_MEMFD_CREATE], [1],
+		  [Non-zero if memfd_create(3) should be used])
+else
+	AC_DEFINE([USE_MEMFD_CREATE], [0],
+		  [Non-zero if memfd_create(3) should be used])
+fi
+
 dnl Check for klibc signal.
 AC_CHECK_FUNC(signal)
 if test "$ac_cv_func_signal" != yes; then
@@ -144,10 +167,18 @@ if test "$ac_cv_func_signal" != yes; then
 fi
 
 dnl Check for stat64 (dietlibc/klibc).
-AC_CHECK_FUNC(stat64,, [
+AC_CHECK_DECL(stat64, AC_CHECK_FUNC(stat64))
+if test "$ac_cv_func_stat64" != yes; then
 	AC_DEFINE(fstat64, fstat, [64-bit operations are the same as 32-bit])
 	AC_DEFINE(lstat64, lstat, [64-bit operations are the same as 32-bit])
 	AC_DEFINE(stat64, stat, [64-bit operations are the same as 32-bit])
+fi
+
+AC_CHECK_FUNC(glob64,, [
+	AC_DEFINE(glob64_t, glob_t, [64-bit operations are the same as 32-bit])
+	AC_DEFINE(glob64, glob, [64-bit operations are the same as 32-bit])
+	AC_DEFINE(globfree64, globfree,
+		  [64-bit operations are the same as 32-bit])
 ])
 
 dnl OS X apparently has stat64 but not open64.
@@ -173,13 +204,25 @@ if test "$have_st_mtim" = "yes"; then
 		[Define if your `struct stat' has `st_mtim'])
 fi
 
+dnl F_DUPFD_CLOEXEC is a mandatory part of POSIX since Issue 7
+AC_MSG_CHECKING(for F_DUPFD_CLOEXEC)
+AC_COMPILE_IFELSE(
+[AC_LANG_PROGRAM([#include <unistd.h>
+#include <fcntl.h>],
+[return fcntl(0, F_DUPFD_CLOEXEC, 0)])],
+have_dupfd_cloexec=1, have_dupfd_cloexec=0)
+AC_MSG_RESULT($(expr yes \& $have_dupfd_cloexec \| no))
+AC_DEFINE_UNQUOTED([HAVE_F_DUPFD_CLOEXEC], [$have_dupfd_cloexec],
+	[Define to 1 your system supports F_DUPFD_CLOEXEC])
+
 AC_ARG_WITH(libedit, AS_HELP_STRING(--with-libedit, [Compile with libedit support]))
 use_libedit=
 if test "$with_libedit" = "yes"; then
 	AC_CHECK_LIB(edit, history_init, [
 		AC_CHECK_HEADER([histedit.h], [use_libedit="yes"],
 				AC_MSG_ERROR(
-					[Can't find required header files.]))])
+					[Can't find required header files.]))], [
+		AC_MSG_ERROR([Can't find libedit.])])
 fi
 if test "$use_libedit" != "yes"; then
 	AC_DEFINE([SMALL], 1, [Define if you build with -DSMALL])

{libdash-0.3 → libdash-0.4.0}/libdash/parser.py

@@ -11,11 +11,11 @@ def libdash_library_path():
 
     if LIBDASH_LIBRARY_PATH is not None:
         return LIBDASH_LIBRARY_PATH
-    
+
     FILE_PATH = os.path.dirname(os.path.realpath(os.path.abspath(__file__)))
     LIBDASH_LIBRARY_PATH = os.path.join(FILE_PATH, "libdash.so")
     return LIBDASH_LIBRARY_PATH
-    
+
 EOF_NLEFT = -99; # libdash/src/input.c
 
 class ParsingException(Exception):
@@ -83,8 +83,9 @@ def parse(inputPath, init=True):
 
                     # Last line did not have a newline
                     assert (len (lines [-1]) > 0 and (lines [-1][-1] != '\n'))
-            else:
-                assert (nleft_after == 0); # Read whole lines
+            elif nleft_after != 0:
+                # we formerly asserted that `nleft_after != 0`, but this no longer holds
+                linno_after = linno_after + 1; # The last line wasn't counted
 
             n_ptr = cast (n_ptr_C, POINTER (union_node))
             new_ast = of_node (n_ptr)

{libdash-0.3 → libdash-0.4.0}/libdash/printer.py

@@ -15,6 +15,10 @@ STRING_OF_VAR_TYPE_DICT = {
     "Length"   : "#"
 };
 
+UNQUOTED = 0 # everything escaped
+QUOTED = 1   # only escape special characters
+HEREDOC = 2  # like QUOTED, but _don't_ escape double quotes
+QUOTE_MODES = [UNQUOTED, QUOTED, HEREDOC]
 
 # dash.ml
 #
@@ -324,25 +328,27 @@ def escaped (param):
 #      "${" ^ name ^ (if nul then ":" else "") ^ string_of_var_type vt ^ string_of_arg a ^ "}"
 #   | Q a -> "\"" ^ string_of_arg a ^ "\""
 #   | B t -> "$(" ^ to_string t ^ ")"
-def string_of_arg_char (c, is_quoted=False):
+def string_of_arg_char (c, quote_mode=UNQUOTED):
     (type, param) = c;
 
     if (type == "E"):
         char = chr (param);
 
-        ## MMG 2021-09-20 It might be safe to move everything except for " in the second list, but no need to do it if the tests pass 
+        ## MMG 2021-09-20 It might be safe to move everything except for " in the second list, but no need to do it if the tests pass
+        ## '!' dropped for bash non-interactive bash compatibility
         ## Chars to escape unconditionally
-        chars_to_escape = ["'", '"', '`', '(', ')', '{', '}', '$', '!', '&', '|', ';']
+        chars_to_escape = ["'", '"', '`', '(', ')', '{', '}', '$', '&', '|', ';']
         ## Chars to escape only when not quoted
         chars_to_escape_when_no_quotes = ['*', '?', '[', ']', '#', '<', '>', '~', ' ']
         if char in chars_to_escape:
             return '\\' + char
-        elif char in chars_to_escape_when_no_quotes and not is_quoted:
+        elif char in chars_to_escape_when_no_quotes and quote_mode==UNQUOTED:
             return '\\' + char
         else:
             return escaped (param)
     elif (type == "C"):
-        if chr(param) == '"':
+        # HEREDOC should never escape double quotes per POSIX 2.7.4
+        if quote_mode==QUOTED and chr(param) == '"':
             return '\\"'
         else:
             return chr (param);
@@ -360,7 +366,7 @@ def string_of_arg_char (c, is_quoted=False):
             print ("Unexpected param for T: %s" % param);
             abort ();
     elif (type == "A"):
-        return "$((" + string_of_arg (param, is_quoted) + "))";
+        return "$((" + string_of_arg (param, quote_mode) + "))";
     elif (type == "V"):
         assert (len (param) == 4);
         if (param [0] == "Length"):
@@ -381,13 +387,20 @@ def string_of_arg_char (c, is_quoted=False):
             else:
                 os.abort (); # For my own sanity
 
-            stri += string_of_var_type (vt) + string_of_arg (a, is_quoted) + "}";
+            stri += string_of_var_type (vt) + string_of_arg (a, quote_mode) + "}";
 
             return stri;
     elif (type == "Q"):
-        return "\"" + string_of_arg (param, is_quoted=True) + "\"";
+        return "\"" + string_of_arg (param, quote_mode=QUOTED) + "\"";
     elif (type == "B"):
-        return "$(" + to_string (param) + ")";
+        body = to_string (param)
+        # to handle $( () )
+        try:
+            if body[0] == "(" and body[-1] == ")":
+                body = f" {body} "
+        except IndexError:
+            pass
+        return "$(" + body + ")"
     else:
         abort ();
 
@@ -395,21 +408,14 @@ def string_of_arg_char (c, is_quoted=False):
 # and string_of_arg = function
 #   | [] -> ""
 #   | c :: a -> string_of_arg_char c ^ string_of_arg a
-def string_of_arg (args, is_quoted=False):
+def string_of_arg (args, quote_mode=UNQUOTED):
     # print (args);
 
     i = 0
     text = []
     while i < len(args):
-        c = string_of_arg_char(args[i], is_quoted)
-
-        # dash will parse '$?' as
-        # [(C, '$'), (E, '?')]
-        # but we don't normally want to escape ?
-        #
-        # so we check up after the fact: if the character after $ is escaped,
-        # we'll escape the $, too
-        if c == "$" and (i+1 < len(args)) and args[i+1][0] == "E":
+        c = string_of_arg_char(args[i], quote_mode=quote_mode)
+        if c == "$" and (i+1 < len(args)):
             c = "\\$"
         text.append(c)
 
@@ -526,7 +532,8 @@ def string_of_redir (redir):
     elif (type == "Heredoc"):
         (t, fd, a) = params;
 
-        heredoc = string_of_arg (a, is_quoted = True);
+        # MMG 2022-08-23 not quite correct 
+        heredoc = string_of_arg (a, quote_mode=HEREDOC);
         marker = fresh_marker0 (heredoc);
 
         stri = show_unless (0, fd) + "<<";

libdash-0.4.0/libdash.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.1
+Name: libdash
+Version: 0.4.0
+Summary: Bindings for the dash shell as a library
+Author: PaSh contributors
+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/binpash/libdash
+Project-URL: Bug Tracker, https://github.com/binpash/libdash/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: System Shells
+Classifier: Operating System :: POSIX
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: COPYING
+
+[![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.
+
+# Pretty printing
+
+The pretty printer does its best to produce valid shell scripts, but it's possible to manually construct AST nodes that don't directly correspond to valid scripts.
+
+For example, the Python AST `[[['Q', [['C', 34]]]]]` represents a quoted field containing a double quote character. Translated literally, this would yield the string `"""`, which is not a valid shell script. The pretty printer will instead automatically escape the inner quote, rendering `"\""`.
+
+While the printer tries to get things right either way, you should use escapes to signal to the printer when to escape: you should use the Python AST `[[['Q', [['E', 34]]]]]` to mark the inner double quote as escaped.
+
+# Known issues
+
+We currently do not escape the character `!` (exclamation point). In an interactive shell, `!` is likely treated as a history substitution (and so should be escaped), but in a non-interactive shell, `!` is treated normally. We currently cater to non-interactive shells; eventually this behavior will be controllable.

{libdash-0.3 → libdash-0.4.0}/libdash.egg-info/SOURCES.txt

@@ -75,6 +75,7 @@ src/system.c
 src/system.h
 src/trap.c
 src/trap.h
+src/type_description.ml
 src/var.c
 src/var.h
 src/bltin/bltin.h

{libdash-0.3 → libdash-0.4.0}/pyproject.toml

@@ -1,23 +1,24 @@
 [project]
 name = "libdash"
-version = "0.3"
+version = "0.4.0"
 authors = [
   { name="Michael Greenberg", email="michael@greenberg.science" },
+  { name="PaSh contributors" },
 ]
+license = { file = "COPYING" }
 description = "Bindings for the dash shell as a library"
 readme = "README.md"
-license = { file="COPYING" }
 requires-python = ">=3.7"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Topic :: System :: System Shells",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: POSIX",
 ]
 
+
 [project.urls]
-"Homepage" = "https://github.com/mgree/libdash"
-"Bug Tracker" = "https://github.com/mgree/libdash/issues"
+"Homepage" = "https://github.com/binpash/libdash"
+"Bug Tracker" = "https://github.com/binpash/libdash/issues"
 
 [build-system]
 requires = ["setuptools>=61.0"]