refactor!: convert plcc.py to python package plcc

BREAKING CHANGE:

plcc is now a Python package, and plcc.py has been removed.
So plcc.py can no longer be called directly like this

    python3 path/to/plcc.py grammar

Instead, use plcc like this

    plcc grammar

---

This commit restructures the PLCC codebase into that of a
conventional Python project. This should make it easier to
redesign the internal structure of PLCC, making it easier to
maintain and add new functionality. It should also help us
prepare to distribute PLCC through PyPI, making it easier
to install. Here is a summary of changes.

- Convert plcc.py into python package plcc
- Remove environment variable LIBPLCC
- Move src/Std/ under src/plcc (the PLCC Python package)
- Move lib/jackson under src/plcc (the PLCC Python package)
- Pull common functionality of scripts into common.bash

---

Related Issues

- Related to #119
- Closes #121
- Closes #120

.gitpod.yml

@@ -7,10 +7,8 @@ tasks:
       echo "INSTALLING latest JAVA (a PLCC dependency)"
       sdk install java < /dev/null
       echo ""
-      echo "INSTALLING PLCC in $GITPOD_REPO_ROOT/src"
-      echo 'export LIBPLCC="$GITPOD_REPO_ROOT/src"
-      export PATH="$LIBPLCC:$PATH"
-      ' >> "$HOME/.bashrc"
+      echo "INSTALLING PLCC from source"
+      echo 'export PATH="$GITPOD_REPO_ROOT/src/plcc/bin:$PATH"' >> "$HOME/.bashrc"
       echo ""
       echo "INSTALLING reuse (for licenses: https://reuse.software/)"
       pip install --upgrade pip

.reuse/dep5

@@ -15,6 +15,6 @@ Copyright:
   Copyright (C) 2023  PLCC Community <https://discord.gg/EVtNSxS9E2>
 License: GPL-3.0-or-later
 
-Files: lib/jackson/*
+Files: plcc/lib/jackson/*
 Copyright: Copyright 2007-, Tatu Saloranta (tatu.saloranta@iki.fi)
-License: Apache-2.0
+License: Apache-2.0

README.md

@@ -47,8 +47,9 @@ image: gitpod/workspace-full:latest
 tasks:
   - name: Install PLCC
     command: |
-        /bin/bash -c "$(\curl -fsSL https://github.com/ourPLCC/plcc/raw/main/installers/plcc/install.bash)" \
-          >> ~/.bashrc
+        /bin/bash -c "$(\
+          \curl -fsSL https://github.com/ourPLCC/plcc/raw/main/installers/plcc/install.bash \
+        )" >> ~/.bashrc
         exec bash
 ```
 

containers/configurable/Dockerfile

@@ -45,4 +45,4 @@ RUN bash -c 'curl -s https://get.sdkman.io | bash'
 RUN bash -c "source $HOME/.sdkman/bin/sdkman-init.sh && sdk install java $JAVA_VERSION"
 
 COPY --chown=$USERNAME:$USERNAME . $HOME/.plcc
-ENV PATH="$HOME/.plcc/src:${PATH}" LIBPLCC="$HOME/.plcc/src"
+ENV PATH="$HOME/.plcc/src/plcc/bin:${PATH}"

containers/plcc/Dockerfile

@@ -28,7 +28,7 @@ RUN addgroup -S my && adduser -S my -G my
 
 # Copy over plcc from downloader stage.
 COPY --chown=plcc:plcc . /plcc
-ENV PATH="/plcc/src:${PATH}" LIBPLCC="/plcc/src"
+ENV PATH="/plcc/src/plcc/bin:${PATH}"
 
 # Change user to dev.
 WORKDIR /workdir

installers/plcc/env.bash

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
+PLCC_DIR="$(dirname -- "${BASH_SOURCE[0]}" )/../.."
+PLCC_DIR="$(cd -- "${PLCC_DIR}" &> /dev/null && pwd)"
 
 echo "
-export LIBPLCC=\"${HOME}/.local/lib/plcc/src\"
-export PATH=\"\${LIBPLCC}:\$PATH\"
+export PATH=\"${PLCC_DIR}/src/plcc/bin:\$PATH\"
 function plcc-con() {
     docker run --rm -it -v \"\$PWD:/workdir\" --user \"\$(id -u):\$(id -g)\" ghcr.io/ourplcc/plcc:latest \"\$@\"
 }
-"
+"

installers/plcc/install.bash

@@ -3,6 +3,6 @@
 set -euo pipefail
 
 PLCC_HOME="${HOME}/.local/lib/plcc"
-git clone https://github.com/ourPLCC/plcc.git "${PLCC_HOME}"
+git clone -b "${PLCC_GIT_BRANCH:-main}" https://github.com/ourPLCC/plcc.git "${PLCC_HOME}"
 echo "# Add the following line to the end of your .bashrc or .zshrc"
-"${PLCC_HOME}/installers/plcc/rchook.bash"
+"${PLCC_HOME}/installers/plcc/rchook.bash"

src/plcc.py → src/plcc/__main__.py

@@ -21,12 +21,13 @@
 import sys
 import re
 import os
+import pathlib
 import io
 import shutil
 import tempfile
 
-from langs.java import spec as java_spec
-from langs.python import spec as python_spec
+from plcc.java import spec as java_spec
+from plcc.python import spec as python_spec
 
 argv = sys.argv[1:] # skip over the command-line argument
 
@@ -72,10 +73,7 @@ def debug2(msg):
     debug(msg, level=2)
 
 def LIBPLCC():
-    try:
-        return os.environ['LIBPLCC']
-    except KeyError:
-        death("undefined LIBPLCC environment variable -- quitting")
+    return str(pathlib.Path(__file__).parent)
 
 def main():
     global argv
@@ -108,8 +106,8 @@ def main():
 
     # Handle --version option.
     if 'version' in flags and flags['version']:
-        import version
-        print(version.get_version())
+        import plcc.version
+        print(plcc.version.get_version())
         sys.exit(0)
 
     jsonAstInit()
@@ -257,7 +255,7 @@ def lexFinishUp():
     if not dst:
         death('illegal destdir flag value')
     try:
-        os.mkdir(dst)
+        os.mkdir(str(dst))
         debug('[lexFinishUp] ' + dst + ': destination subdirectory created')
     except FileExistsError:
         debug('[lexFinishUp] ' + dst + ': destination subdirectory exists')
@@ -267,15 +265,13 @@ def lexFinishUp():
     if not getFlag('Token'):
         return # do not create any automatically generated scanner-related files
     libplcc = getFlag('libplcc')
-    if not libplcc:
-        death('illegal libplcc flag value')
-    std = libplcc + '/Std'
+    std = pathlib.Path(libplcc) / 'lib' / 'Std'
     try:
-        os.mkdir(std)
+        os.mkdir(str(std))
     except FileExistsError:
         pass
     except:
-        death(std + ': cannot access directory')
+        death(str(std) + ': cannot access directory')
     fname = '{}/{}'.format(dst, 'Token.java')
     try:
         tokenFile = open(fname, 'w')
@@ -392,7 +388,7 @@ def parFinishUp():
     # copy the Std parser-related files
     dst = getFlag('destdir')
     libplcc = getFlag('libplcc')
-    std = libplcc + '/Std'
+    std = pathlib.Path(libplcc) / 'lib' / 'Std'
     for fname in STDP:
         if getFlag(fname):
             debug('[parFinishUp] copying {} from {} to {} ...'.format(fname, std, dst))
@@ -891,7 +887,7 @@ def semFinishUp(stubs, destFlag='destdir', ext='.java'):
     if not dst:
         death('illegal destdir flag value')
     try:
-        os.mkdir(dst)
+        os.mkdir(str(dst))
         debug('[semFinishUp] ' + dst + ': destination subdirectory created')
     except FileExistsError:
         debug('[semFinishUp] ' + dst + ': destination subdirectory exists')

src/plcc/bin/common.bash

@@ -0,0 +1,47 @@
+
+init() {
+    set -euo pipefail
+    if is_first_call_to_init ; then return 0 ; fi
+    define_PLCC_DIR
+    update_PYTHONPATH
+    update_CLASSPATH
+}
+
+is_first_call_to_init() {
+    if [[ -n "${PLCC_FIRST_CALL_TO_INIT:-}" ]] ; then
+        return 0
+    else
+        PLCC_FIRST_CALL_TO_INIT='false'
+        export PLCC_FIRST_CALL_TO_INIT
+        return 1
+    fi
+}
+
+define_PLCC_DIR() {
+    PLCC_DIR="$( abspath "$( dirname -- "${BASH_SOURCE[0]}" )/../.." )"
+    export PLCC_DIR
+}
+
+update_PYTHONPATH() {
+    PYTHONPATH="${PYTHONPATH:+${PYTHONPATH}:}${PLCC_DIR}"
+    export PYTHONPATH
+}
+
+update_CLASSPATH() {
+    JACKSON_VERSION="2.15.2"
+    JACKSON_ANNOTATIONS="${PLCC_DIR}/plcc/lib/jackson/jackson-annotations-${JACKSON_VERSION}.jar"
+    JACKSON_CORE="${PLCC_DIR}/plcc/lib/jackson/jackson-core-${JACKSON_VERSION}.jar"
+    JACKSON_DATABIND="${PLCC_DIR}/plcc/lib/jackson/jackson-databind-${JACKSON_VERSION}.jar"
+    CP="./Java:${JACKSON_ANNOTATIONS}:${JACKSON_CORE}:${JACKSON_DATABIND}"
+    CLASSPATH="${CLASSPATH:+${CLASSPATH}:}${CP}"
+    export CLASSPATH
+}
+
+abspath() { echo "$( cd -- "${1}" &> /dev/null && pwd )" ; }
+
+assert_file_exists (){
+    [ -f "${1}" ] || {
+        echo "${1} missing" >&2
+        exit 2
+    }
+}

src/plcc/bin/parse

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+source "$(dirname -- "${BASH_SOURCE[0]}" )/common.bash" && init
+
+assert_file_exists Java/Parse.class
+
+if  echo "$*" | grep -- "--json_ast" &> /dev/null
+then
+
+    ARGS=()
+    while [ $# -gt 0 ] ; do
+        case "$1" in
+            --json_ast)
+                shift
+            ;;
+            *)
+                ARGS+=("$1")
+                shift
+            ;;
+        esac
+    done
+
+    if ! java ParseJsonAst "${ARGS[@]}" ; then
+        >&2 echo "Did you forget to pass --json_ast to plccmk?"
+        exit 1
+    fi
+else
+    java Parse "$@"
+fi

src/plcc/bin/plcc

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+source "$(dirname -- "${BASH_SOURCE[0]}" )/common.bash" && init
+
+python3 -m plcc "$@"

src/plcc/bin/plccmk

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+source "$(dirname -- "${BASH_SOURCE[0]}" )/common.bash" && init
+
+if [[ "${1:-}" == "-c" ]]
+then
+        rm -f Java/*.java Java/*.class
+        shift
+fi
+
+if [ $# -eq 0 ]
+then
+        DEFAULT=spec
+        [ -f "$DEFAULT" ] || DEFAULT=grammar
+        set - $DEFAULT
+fi
+
+plcc "$@"
+(cd ./Java ; javac *.java)

src/plcc/bin/rep

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+source "$(dirname -- "${BASH_SOURCE[0]}" )/common.bash" && init
+
+assert_file_exists Java/Rep.class
+java Rep "$@"

src/plcc/bin/scan

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+source "$(dirname -- "${BASH_SOURCE[0]}" )/common.bash" && init
+
+assert_file_exists Java/Scan.class
+java Scan