jcl-parser 2.0.0__tar.gz → 2.0.1__tar.gz

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jcl-parser
-Version: 2.0.0
+Version: 2.0.1
 Summary: Parse IBM JCL (Job Control Language) scripts into Python objects
 Author-email: JCL Parser Team <team@jclparser.dev>
 License: AGPL-3.0-or-later

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jcl_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jcl-parser
-Version: 2.0.0
+Version: 2.0.1
 Summary: Parse IBM JCL (Job Control Language) scripts into Python objects
 Author-email: JCL Parser Team <team@jclparser.dev>
 License: AGPL-3.0-or-later

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jcl_parser.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ jclparser/lint/runner.py
 jclparser/plugins/__init__.py
 jclparser/plugins/base.py
 jclparser/program_profiles/__init__.py
+jclparser/program_profiles/_control.py
 jclparser/program_profiles/_invoked.py
 jclparser/program_profiles/adrdssu.py
 jclparser/program_profiles/base.py

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/__init__.py

@@ -20,7 +20,7 @@ application, for example::
 import logging as _logging
 
 # Package metadata
-__version__ = "2.0.0"  # x-release-please-version
+__version__ = "2.0.1"  # x-release-please-version
 __author__ = "JCL Parser Team"
 __description__ = "Parse IBM JCL scripts into Python objects"
 

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/_job_builder.py

@@ -611,9 +611,19 @@ class JobBuilder:
                 self.pending_jes_typed.append(typed)
 
     def _on_output(self, stmt: Statement, line_num: int) -> None:
-        # OUTPUT statement - JES output descriptor; promote to typed model
+        # OUTPUT statement - JES output descriptor; promote to typed model.
+        # Coded after an EXEC it is step-level, before the first EXEC
+        # job-level (or, in a PROC body, procedure-level): DD OUTPUT=*.name
+        # resolution depends on which (#85).
+        step = self.current_step
+        procedure = self.current_procedure
+        output = OutputStatement.from_statement(
+            stmt,
+            step_name=(step.name or "") if step is not None else None,
+            procedure_name=procedure.name if procedure is not None else None,
+        )
         sink = self.job.output_statements if self.job else self.pending_outputs
-        sink.append(OutputStatement.from_statement(stmt))
+        sink.append(output)
 
     def _on_null(self, stmt: Statement, line_num: int) -> None:
         # NULL statement (//) - just ignore, used as delimiter

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/_post_parse.py

@@ -24,7 +24,7 @@ from typing import TYPE_CHECKING, Any
 
 from ._model_factories import _has_unresolved_symbol_ref
 from .errors import JCLStructureError, JCLSyntaxError
-from .model import Job, Step, iter_execution_steps
+from .model import Job, OutputStatement, Step, iter_execution_steps
 from .utils import split_source_lines
 
 if TYPE_CHECKING:
@@ -48,64 +48,124 @@ def _extract_output_ref_names(value: Any) -> list[str]:
     Values that do not start with ``*.`` (e.g. a bare nodename, a qualified
     ``STEP.PROCSTEP.N`` form without the leading ``*.``, or ``None``) yield
     an empty list.  Callers rely on this to distinguish output-statement
-    references from other uses of the OUTPUT= parameter.
+    references from other uses of the OUTPUT= parameter.  The step
+    qualifiers are kept by :func:`_extract_output_refs`.
+    """
+    return [ref[-1] for ref in _extract_output_refs(value)]
+
+
+def _extract_output_refs(value: Any) -> list[tuple[str, ...]]:
+    """Return the ``*.`` OUTPUT references of a DD ``OUTPUT=`` value, qualified.
+
+    Each reference is the tuple of its uppercased segments::
+
+        OUTPUT=*.NAME                -> [("NAME",)]
+        OUTPUT=(*.STEP.NAME,*.N2)    -> [("STEP", "NAME"), ("N2",)]
+        OUTPUT=*.STEP.PROCSTEP.NAME  -> [("STEP", "PROCSTEP", "NAME")]
     """
-    names: list[str] = []
     items: list[str]
     if isinstance(value, list):
         items = [str(v) for v in value]
     elif isinstance(value, str):
         items = [value]
     else:
-        return names
+        return []
 
+    refs: list[tuple[str, ...]] = []
     for item in items:
         token = item.strip().strip("()")
         if not token.startswith("*."):
-            # Qualified form step.procstep.name uses ".name" — last segment after *
-            if ".*" in token:
-                # Not a back-reference either
-                continue
-            continue
-        ref = token[2:].strip()
-        if not ref:
             continue
-        # If qualified like STEP.PROCSTEP.NAME, take the final segment.
-        if "." in ref:
-            ref = ref.split(".")[-1]
-        names.append(ref.upper())
-    return names
+        segments = tuple(seg.strip().upper() for seg in token[2:].split("."))
+        if segments[-1]:
+            refs.append(segments)
+    return refs
+
+
+#: Key of an OUTPUT statement in :class:`_OutputScopes`:
+#: ``(procedure_name, step_name, name)``, uppercased; ``None`` for a level
+#: the statement is not coded in.
+_OutputKey = tuple[str | None, str | None, str]
+
+
+def _upper(name: str | None) -> str | None:
+    return name.upper() if name is not None else None
+
+
+class _OutputScopes:
+    """The job's OUTPUT statements, by the step (and PROC) they are coded in."""
+
+    def __init__(self, job: Job) -> None:
+        self.by_key: dict[_OutputKey, OutputStatement] = {}
+        for out in job.output_statements:
+            if out.name:
+                key = (
+                    _upper(out.procedure_name),
+                    _upper(out.step_name),
+                    out.name.upper(),
+                )
+                self.by_key[key] = out  # last wins if duplicated
+        self.instream_procs = {p.name.upper() for p in job.procedures}
+        self.step_procs = {
+            step.name.upper(): (step.procedure or "").upper()
+            for step in iter_execution_steps(job.steps)
+            if step.name
+        }
+
+    def checkable(self, ref: tuple[str, ...]) -> bool:
+        """False for ``*.step.procstep.name`` into a PROC that is not in-stream.
+
+        Its OUTPUT statements are not part of the job, so whether the
+        reference resolves cannot be told.
+        """
+        return len(ref) != 3 or self.step_procs.get(ref[0]) in self.instream_procs
+
+    def resolve(self, ref: tuple[str, ...], step_name: str) -> OutputStatement | None:
+        """The OUTPUT statement *ref* names from a DD in job step *step_name*.
+
+        ``*.name`` is the one in the DD's own step, else the job-level one;
+        ``*.step.name`` the one in job step *step*; ``*.step.procstep.name``
+        the one in step *procstep* of the in-stream PROC job step *step*
+        calls.
+        """
+        name = ref[-1]
+        if len(ref) == 1:
+            own = self.by_key.get((None, step_name.upper(), name))
+            return own if own is not None else self.by_key.get((None, None, name))
+        if len(ref) == 2:
+            return self.by_key.get((None, ref[0], name))
+        if len(ref) == 3:
+            return self.by_key.get((self.step_procs.get(ref[0]), ref[1], name))
+        return None
 
 
 def _resolve_output_refs(job: Job) -> None:
     """Populate ``DDStatement.output_refs`` for every DD that uses ``OUTPUT=*.X``.
 
-    Unresolved references (no matching :class:`OutputStatement`) are recorded
-    on ``job.unresolved_output_refs`` as ``(step_name, ref_name, line_number)``
-    tuples so :func:`jclparser.validators.validate_job_structure` can emit
-    warnings without re-scanning the parameter string.
+    A reference resolves by scope, not by name alone (#85): see
+    :meth:`_OutputScopes.resolve`. Unresolved references (no matching
+    :class:`OutputStatement`) are recorded on ``job.unresolved_output_refs``
+    as ``(step_name, ref, line_number)`` tuples, *ref* as coded after ``*.``
+    (``"NAME"``, ``"STEP.NAME"``), so
+    :func:`jclparser.validators.validate_job_structure` can emit warnings
+    without re-scanning the parameter string. A reference into a PROC that
+    is not in-stream cannot be checked and is neither.
     """
     if not job:
         return
-    # Index OUTPUT statements by uppercased name (last wins if duplicated).
-    output_by_name: dict[str, Any] = {
-        out.name.upper(): out for out in job.output_statements if out.name
-    }
-
-    from .model import iter_execution_steps
-
+    scopes = _OutputScopes(job)
     for step in iter_execution_steps(job.steps):
         for dd in step.dd_statements:
             value = dd.parameters.get("OUTPUT")
             if value is None:
                 continue
-            for ref in _extract_output_ref_names(value):
-                target = output_by_name.get(ref)
+            for ref in _extract_output_refs(value):
+                target = scopes.resolve(ref, step.name or "")
                 if target is not None:
                     dd.output_refs.append(target)
-                else:
+                elif scopes.checkable(ref):
                     job.unresolved_output_refs.append(
-                        (step.name or "", ref, dd.line_number)
+                        (step.name or "", ".".join(ref), dd.line_number)
                     )
 
 

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/_statement_parser.py

@@ -173,17 +173,36 @@ def _resumes_operands(text: str) -> bool:
     return "=" in token.split(",")[0]
 
 
-def _find_comment_start(operands: str) -> int | None:
+def _closes_parens(text: str, depth: int) -> bool:
+    """Return True if *text*, read at paren *depth*, brings the depth to 0."""
+    in_quotes = False
+    for char in text:
+        if char == "'":
+            in_quotes = not in_quotes
+        elif not in_quotes:
+            if char == "(":
+                depth += 1
+            elif char == ")":
+                depth -= 1
+                if depth <= 0:
+                    return True
+    return False
+
+
+def _find_comment_start(operands: str, depth: int = 0) -> int | None:
     """Index of the comment field inside *operands*, or ``None`` if there is none.
 
     The operand field ends at the first blank that is outside quotes and
     outside parentheses; everything after it is the comment field (z/OS JCL
-    Reference, "Comment field").
+    Reference, "Comment field"). Inside a parenthesised list, a blank that
+    follows a subparameter's comma also starts a comment when the rest of
+    the record neither resumes operands nor closes the list: the list goes
+    on in the next record. *depth* is the paren depth the record starts at
+    (non-zero for a record continuing an open list).
     """
     if " " not in operands and "\t" not in operands:
         # No blank at all: the operand field runs to the end of the record.
         return None
-    depth = 0
     in_quotes = False
     i = 0
     n = len(operands)
@@ -207,6 +226,16 @@ def _find_comment_start(operands: str) -> int | None:
                     i = n - len(rest)
                     continue
                 return i
+            elif (
+                char.isspace()
+                and operands[:i].endswith(",")
+                and not _resumes_operands(operands[i:].lstrip())
+                and not _closes_parens(operands[i:], depth)
+            ):
+                # A parenthesised list interrupted after a subparameter's
+                # comma may carry a comment (z/OS JCL Reference, "Continuing
+                # the operand field"); the list resumes on the next record.
+                return i
         i += 1
     return None
 
@@ -240,7 +269,9 @@ def _find_then_end(operands: str) -> int | None:
     return None
 
 
-def split_comment_field(line: str, group_operation: str = "") -> tuple[str, str]:
+def split_comment_field(
+    line: str, group_operation: str = "", paren_depth: int = 0
+) -> tuple[str, str]:
     """Split a JCL statement record into ``(statement, comment)``.
 
     In JCL a statement's operand field ends at the first blank outside quotes
@@ -270,7 +301,7 @@ def split_comment_field(line: str, group_operation: str = "") -> tuple[str, str]
         if cut is None:
             return line, ""
         return (line[:start] + operands[:cut]).rstrip(), operands[cut:].strip()
-    cut = _find_comment_start(operands)
+    cut = _find_comment_start(operands, paren_depth)
     if cut is None:
         return line, ""
     return (line[:start] + operands[:cut]).rstrip(), operands[cut:].strip()

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/condition_parser.py

@@ -363,6 +363,20 @@ def _tokenize(text: str) -> list[str]:  # noqa: C901 -- complexity baseline, spl
 # ---------------------------------------------------------------------------
 
 
+def _split_step_ref(token: str) -> tuple[str | None, str]:
+    """Split ``[STEP.[INNER.]]ATTR`` into ``(step_name, ATTR)`` (uppercased).
+
+    The three-level form ``OUTERST.INNERST.ATTR`` (a step of an exploded
+    PROC) yields the step name ``OUTERST.INNERST``.
+    """
+    if "." not in token:
+        return None, token.upper()
+    parts = token.split(".", 2)  # at most 3 parts
+    if len(parts) == 3:
+        return f"{parts[0]}.{parts[1]}".upper(), parts[2].upper()
+    return parts[0].upper(), parts[1].upper()
+
+
 class _Parser:
     """Internal recursive-descent parser for condition expressions."""
 
@@ -419,7 +433,7 @@ class _Parser:
             return NotCondition(self._parse_not())
         return self._parse_primary()
 
-    def _parse_primary(self) -> ConditionNode:  # noqa: C901 -- complexity baseline, split when touched
+    def _parse_primary(self) -> ConditionNode:
         tok = self._peek()
         if tok is None:
             raise ValueError("Unexpected end of condition expression")
@@ -439,74 +453,63 @@ class _Parser:
         # produced after PROC explosion; "PROCSTEP.INNERSTEP" is used as the
         # step-name key in step_results).
         token = self._consume()
-        step_name: str | None = None
-        attr: str
-
-        if "." in token:
-            parts = token.split(".", 2)  # at most 3 parts
-            if len(parts) == 3:
-                # Three-level: OUTERST.INNERST.ATTR
-                step_name = f"{parts[0]}.{parts[1]}".upper()
-                attr = parts[2].upper()
-            else:
-                step_name = parts[0].upper()
-                attr = parts[1].upper()
-        else:
-            attr = token.upper()
+        step_name, attr = _split_step_ref(token)
 
         if attr == "ABEND":
             return self._boolean_test(AbendCondition(step_name=step_name))
-
         if attr == "RUN":
             return self._boolean_test(RunCondition(step_name=step_name))
-
         if attr == "RC":
-            op_tok = self._peek()
-            op = _OP_MAP.get(op_tok.upper()) if op_tok else None
-            if op is None:
-                # ``RC`` is not a Boolean: without a comparison it tests
-                # nothing, and reading it as ``RC EQ 0`` invents one.
-                raise ValueError(f"Expected an operator after RC, got {op_tok!r}")
-
-            self._consume()  # consume operator
+            return self._rc_comparison(step_name)
+        if _RE_DIGITS.match(attr) and step_name is None:
+            return self._value_first_comparison(attr)
+        raise ValueError(f"Unrecognised condition atom: {token!r}")
 
-            val_tok = self._peek()
-            if val_tok is not None and _RE_DIGITS.match(val_tok):
-                self._consume()
-                return ReturnCodeCondition(
-                    step_name=step_name, operator=op, value=int(val_tok)
-                )
-
-            # A non-numeric value (e.g. an unresolved &SYMBOL) cannot be
-            # compared; reading it as 0 would invent a different condition.
-            raise ValueError(f"Expected a numeric RC value, got {val_tok!r}")
-
-        # Bare number first: ``value op [STEP.]RC`` (rare).  The operands are
-        # the other way round, so the operator is mirrored -- ``4 LT RC``
-        # holds when RC is greater than 4, i.e. ``RC GT 4``.
-        if _RE_DIGITS.match(attr):
-            op_tok = self._peek()
-            op = _OP_MAP.get(op_tok.upper()) if op_tok else None
-            if op:
-                self._consume()
-                # After the operator the user may have written "RC" or a step ref
-                next_tok = self._peek()
-                ref = next_tok.upper() if next_tok else ""
-                if ref == "RC" or ref.endswith(".RC"):
-                    self._consume()
-                    ref_step = ref[: -len(".RC")] if ref != "RC" else None
-                    return ReturnCodeCondition(
-                        step_name=ref_step or None,
-                        operator=_MIRRORED_OP[op],
-                        value=int(attr),
-                    )
-                raise ValueError(f"Expected RC after {attr} {op_tok}, got {next_tok!r}")
-            # Fallback: single number, treat as RC EQ value
+    def _rc_comparison(self, step_name: str | None) -> ConditionNode:
+        """Parse ``op value`` after ``[STEP.]RC``."""
+        op_tok = self._peek()
+        op = _OP_MAP.get(op_tok.upper()) if op_tok else None
+        if op is None:
+            # ``RC`` is not a Boolean: without a comparison it tests
+            # nothing, and reading it as ``RC EQ 0`` invents one.
+            raise ValueError(f"Expected an operator after RC, got {op_tok!r}")
+        self._consume()  # consume operator
+
+        val_tok = self._peek()
+        if val_tok is not None and _RE_DIGITS.match(val_tok):
+            self._consume()
             return ReturnCodeCondition(
-                step_name=step_name, operator="EQ", value=int(attr)
+                step_name=step_name, operator=op, value=int(val_tok)
             )
-
-        raise ValueError(f"Unrecognised condition atom: {token!r}")
+        # A non-numeric value (e.g. an unresolved &SYMBOL) cannot be
+        # compared; reading it as 0 would invent a different condition.
+        raise ValueError(f"Expected a numeric RC value, got {val_tok!r}")
+
+    def _value_first_comparison(self, value: str) -> ConditionNode:
+        """Parse ``op [STEP.]RC`` after a leading number (rare).
+
+        The operands are the other way round, so the operator is mirrored --
+        ``4 LT RC`` holds when RC is greater than 4, i.e. ``RC GT 4``.  A
+        bare number with no comparison tests nothing; reading it as
+        ``RC EQ n`` would invent a condition (issue #86, like the bare
+        ``RC`` of issue #63), so it is rejected.
+        """
+        op_tok = self._peek()
+        op = _OP_MAP.get(op_tok.upper()) if op_tok else None
+        if op is None:
+            raise ValueError(f"Expected an operator after {value}, got {op_tok!r}")
+        self._consume()
+        next_tok = self._peek()
+        ref = next_tok.upper() if next_tok else ""
+        if ref != "RC" and not ref.endswith(".RC"):
+            raise ValueError(f"Expected RC after {value} {op_tok}, got {next_tok!r}")
+        self._consume()
+        ref_step = ref[: -len(".RC")] if ref != "RC" else None
+        return ReturnCodeCondition(
+            step_name=ref_step or None,
+            operator=_MIRRORED_OP[op],
+            value=int(value),
+        )
 
     def _boolean_test(self, node: ConditionNode) -> ConditionNode:
         """Consume an optional ``= TRUE`` / ``= FALSE`` after ABEND or RUN."""

{jcl_parser-2.0.0 → jcl_parser-2.0.1}/jclparser/continuation_handler.py

@@ -300,18 +300,18 @@ class ContinuationLineHandler:
             if not next_stripped:
                 break
 
-            # A continuation record only has a comment field of its own
-            # when the statement so far is syntactically closed (the
-            # blank that starts a comment would otherwise be inside the
-            # quoted string or parenthesised list being continued).
+            # A continuation record has no comment field of its own while
+            # a quoted string is being continued (the blank would be inside
+            # it). Inside a parenthesised list it may have one after a
+            # subparameter's comma, so the open depth is passed along.
             # The comment is only recorded once the record is known to be
             # merged: a record that starts the next statement is stripped
             # (and recorded) again as that statement, which would report
             # the same comment twice.
             next_comment = ""
-            if not cached_ctx.in_quotes and cached_ctx.paren_depth == 0:
+            if not cached_ctx.in_quotes:
                 next_line, next_comment = split_comment_field(
-                    next_line, group_operation
+                    next_line, group_operation, cached_ctx.paren_depth
                 )
 
             # Check if next line is a continuation, passing cached context