exploration.main

  1"""
  2- Authors: Peter Mawhorter
  3- Consulted:
  4- Date: 2022-10-15
  5- Purpose: Main API entry points to support the `__main__.py` script.
  6"""
  7
  8from __future__ import annotations
  9
 10import argparse
 11import pathlib
 12import textwrap
 13import sys
 14import csv
 15import networkx as nx  # type: ignore
 16
 17from typing import (
 18    Literal, Optional, Union, get_args, TypeAlias, List, Callable, Dict,
 19    Sequence
 20)
 21
 22from . import journal
 23from . import core
 24from . import base
 25from . import analysis
 26from . import parsing
 27
 28
 29#------------#
 30# File input #
 31#------------#
 32
 33SourceType: TypeAlias = Literal[
 34    "graph",
 35    "dot",
 36    "exploration",
 37    "journal",
 38]
 39"""
 40The file types we recognize.
 41"""
 42
 43
 44def determineFileType(filename: str) -> SourceType:
 45    if filename.endswith('.dcg'):
 46        return 'graph'
 47    elif filename.endswith('.dot'):
 48        return 'dot'
 49    elif filename.endswith('.exp'):
 50        return 'exploration'
 51    elif filename.endswith('.exj'):
 52        return 'journal'
 53    else:
 54        raise ValueError(
 55            f"Could not determine the file type of file '{filename}':"
 56            f" it does not end with '.dcg', '.dot', '.exp', or '.exj'."
 57        )
 58
 59
 60def loadDecisionGraph(path: pathlib.Path) -> core.DecisionGraph:
 61    """
 62    Loads a JSON-encoded decision graph from a file. The extension
 63    should normally be '.dcg'.
 64    """
 65    with path.open('r', encoding='utf-8-sig') as fInput:
 66        return parsing.loadCustom(fInput, core.DecisionGraph)
 67
 68
 69def saveDecisionGraph(
 70    path: pathlib.Path,
 71    graph: core.DecisionGraph
 72) -> None:
 73    """
 74    Saves a decision graph encoded as JSON in the specified file. The
 75    file should normally have a '.dcg' extension.
 76    """
 77    with path.open('w', encoding='utf-8') as fOutput:
 78        parsing.saveCustom(graph, fOutput)
 79
 80
 81def loadDotFile(path: pathlib.Path) -> core.DecisionGraph:
 82    """
 83    Loads a `core.DecisionGraph` form the file at the specified path
 84    (whose extension should normally be '.dot'). The file format is the
 85    GraphViz "dot" format.
 86    """
 87    with path.open('r', encoding='utf-8-sig') as fInput:
 88        dot = fInput.read()
 89        try:
 90            return parsing.parseDot(dot)
 91        except parsing.DotParseError:
 92            raise parsing.DotParseError(
 93                "Failed to parse Dot file contents:\n\n"
 94              + dot
 95              + "\n\n(See error above for specific parsing issue.)"
 96            )
 97
 98
 99def saveDotFile(path: pathlib.Path, graph: core.DecisionGraph) -> None:
100    """
101    Saves a `core.DecisionGraph` as a GraphViz "dot" file. The file
102    extension should normally be ".dot".
103    """
104    dotStr = parsing.toDot(graph, clusterLevels=[])
105    with path.open('w', encoding='utf-8') as fOutput:
106        fOutput.write(dotStr)
107
108
109def loadExploration(path: pathlib.Path) -> core.DiscreteExploration:
110    """
111    Loads a JSON-encoded `core.DiscreteExploration` object from the file
112    at the specified path. The extension should normally be '.exp'.
113    """
114    with path.open('r', encoding='utf-8-sig') as fInput:
115        return parsing.loadCustom(fInput, core.DiscreteExploration)
116
117
118def saveExploration(
119    path: pathlib.Path,
120    exploration: core.DiscreteExploration
121) -> None:
122    """
123    Saves a `core.DiscreteExploration` object as JSON in the specified
124    file. The file extension should normally be '.exp'.
125    """
126    with path.open('w', encoding='utf-8') as fOutput:
127        parsing.saveCustom(exploration, fOutput)
128
129
130def loadJournal(path: pathlib.Path) -> core.DiscreteExploration:
131    """
132    Loads a `core.DiscreteExploration` object from a journal file
133    (extension should normally be '.exj'). Uses the
134    `journal.convertJournal` function.
135    """
136    with path.open('r', encoding='utf-8-sig') as fInput:
137        return journal.convertJournal(fInput.read())
138
139
140def saveAsJournal(
141    path: pathlib.Path,
142    exploration: core.DiscreteExploration
143) -> None:
144    """
145    Saves a `core.DiscreteExploration` object as a text journal in the
146    specified file. The file extension should normally be '.exj'.
147
148    TODO: This?!
149    """
150    raise NotImplementedError(
151        "DiscreteExploration-to-journal conversion is not implemented"
152        " yet."
153    )
154
155
156def loadSource(
157    path: pathlib.Path,
158    formatOverride: Optional[SourceType] = None
159) -> Union[core.DecisionGraph, core.DiscreteExploration]:
160    """
161    Loads either a `core.DecisionGraph` or a `core.DiscreteExploration`
162    from the specified file, depending on its file extension (or the
163    specified format given as `formatOverride` if there is one).
164    """
165    if formatOverride is not None:
166        format = formatOverride
167    else:
168        format = determineFileType(str(path))
169
170    if format == "graph":
171        return loadDecisionGraph(path)
172    if format == "dot":
173        return loadDotFile(path)
174    elif format == "exploration":
175        return loadExploration(path)
176    elif format == "journal":
177        return loadJournal(path)
178    else:
179        raise ValueError(
180            f"Unrecognized file format '{format}' (recognized formats"
181            f" are 'graph', 'exploration', and 'journal')."
182        )
183
184
185#---------------------#
186# Analysis tool lists #
187#---------------------#
188
189AnalysisResult: TypeAlias = Union[None, bool, str, int, float, complex]
190"""
191A type alias for values we're willing to accept as analysis results.
192These are going to be written to a CSV file that we want to be
193human-readable.
194"""
195
196STEPWISE_DECISION_ANALYSIS_TOOLS: Dict[
197    str,
198    Callable[[base.Situation, base.DecisionID], AnalysisResult]
199] = {
200    "actionCount": analysis.analyzeGraph(analysis.countActionsAtDecision),
201    "branchCount": analysis.analyzeGraph(analysis.countBranches)
202}
203"""
204The analysis functions to apply to each decision in each step when
205analyzing an exploration, and the names for each.
206"""
207
208STEP_ANALYSIS_TOOLS: Dict[
209    str,
210    Callable[[base.Situation], AnalysisResult]
211] = {
212    "currentDecision": analysis.currentDecision,
213    "unexploredCount": analysis.countAllUnexploredBranches,
214    "traversableUnexploredCount": analysis.countTraversableUnexploredBranches,
215    "meanActions": analysis.meanOfResults(
216        analysis.perDecision(
217            analysis.analyzeGraph(analysis.countActionsAtDecision)
218        )
219    ),
220    "meanBranches": analysis.meanOfResults(
221        analysis.perDecision(
222            analysis.analyzeGraph(analysis.countBranches)
223        )
224    ),
225}
226"""
227The analysis functions to apply to each step when analyzing an
228exploration, and the names for each.
229"""
230
231DECISION_ANALYSIS_TOOLS: Dict[
232    str,
233    Callable[
234        [core.DiscreteExploration, base.DecisionID],
235        AnalysisResult
236    ]
237] = {
238    "identity": analysis.lastIdentity,
239    "isVisited": lambda e, d: d in e.allVisitedDecisions(),
240    "revisitCount": analysis.countRevisits,
241}
242"""
243The analysis functions to apply once to each decision in an exploration,
244and the names for each.
245"""
246
247WHOLE_ANALYSIS_TOOLS: Dict[
248    str,
249    Callable[[core.DiscreteExploration], AnalysisResult]
250] = {
251    "stepCount": lambda e: len(e),
252    "finalDecisionCount": lambda e: len(e.getSituation().graph),
253    "meanRevisits": analysis.meanOfResults(
254        analysis.perExplorationDecision(
255            analysis.countRevisits,
256            mode="visited"
257        )
258    )
259}
260"""
261The analysis functions to apply to entire explorations, and the names
262for each.
263"""
264
265
266#---------------#
267# API Functions #
268#---------------#
269
270def show(
271    source: pathlib.Path,
272    formatOverride: Optional[SourceType] = None,
273    step: int = -1
274) -> None:
275    """
276    Shows the graph or exploration stored in the `source` file. You will
277    need to have the `matplotlib` library installed. Consider using the
278    interactive interface provided by the `explorationViewer` module
279    instead. The file extension is used to determine how to load the data,
280    although the `--format` option may override this. '.dcg' files are
281    assumed to be decision graphs in JSON format, '.exp' files are assumed
282    to be exploration objects in JSON format, and '.exj' files are assumed
283    to be exploration journals in the default journal format. If the object
284    that gets loaded is an exploration, the final graph for that
285    exploration will be displayed, or a specific graph may be selected
286    using `--step`.
287    """
288    obj = loadSource(source, formatOverride)
289    if isinstance(obj, core.DiscreteExploration):
290        obj = obj.getSituation(step).graph
291
292    import matplotlib.pyplot # type: ignore
293
294    # This draws the graph in a new window that pops up. You have to close
295    # the window to end the program.
296    nx.draw(obj)
297    matplotlib.pyplot.show()
298
299
300def analyze(
301    source: pathlib.Path,
302    formatOverride: Optional[SourceType] = None,
303    destination: Optional[pathlib.Path] = None,
304    applyTools: Optional[List[str]] = None
305) -> None:
306    """
307    Analyzes the exploration stored in the `source` file. The file
308    extension is used to determine how to load the data, although this
309    may be overridden by the `--format` option. Normally, '.exp' files
310    are treated as JSON-encoded exploration objects, while '.exj' files
311    are treated as journals using the default journal format.
312
313    This applies a number of analysis functions to produce a CSV file
314    showing per-decision-per-step, per-decision, per-step, and
315    per-exploration metrics. A subset of the available metrics may be
316    selected by passing a list of strings for the `applyTools` argument.
317    See the `STEPWISE_DECISION_ANALYSIS_TOOLS`, `STEP_ANALYSIS_TOOLS`,
318    `DECISION_ANALYSIS_TOOLS`, and `WHOLE_ANALYSIS_TOOLS` dictionaries
319    for tool names.
320
321    If no output file is specified, the output will be printed out.
322    """
323    # Load our source exploration object:
324    obj = loadSource(source, formatOverride)
325    if isinstance(obj, core.DecisionGraph):
326        obj = core.DiscreteExploration.fromGraph(obj)
327
328    exploration: core.DiscreteExploration = obj
329
330    # Apply all of the analysis functions (or only just those that are
331    # selected using applyTools):
332
333    wholeRows: List[List[AnalysisResult]] = [['Whole exploration metrics:']]
334    # One row per tool
335    for tool in WHOLE_ANALYSIS_TOOLS:
336        if (applyTools is None) or (tool in applyTools):
337            wholeRows.append(
338                [tool, WHOLE_ANALYSIS_TOOLS[tool](exploration)]
339            )
340
341    decisionRows: List[Sequence[AnalysisResult]] = [
342        ['Per-decision metrics:']
343    ]
344    # One row per tool; one column per decision
345    decisionList = exploration.allDecisions()
346    columns = ['Metric ↓/Decision →'] + decisionList
347    decisionRows.append(columns)
348    for tool in DECISION_ANALYSIS_TOOLS:
349        if (applyTools is None) or (tool in applyTools):
350            row: List[AnalysisResult] = [tool]
351            decisionRows.append(row)
352            for decision in decisionList:
353                row.append(
354                    DECISION_ANALYSIS_TOOLS[tool](exploration, decision)
355                )
356
357    stepRows: List[Sequence[AnalysisResult]] = [
358        ['Per-step metrics:']
359    ]
360    # One row per exploration step; one column per tool
361    columns = ['Step ↓/Metric →']
362    stepRows.append(columns)
363    for i, situation in enumerate(exploration):
364        row = [i]
365        stepRows.append(row)
366        for tool in STEP_ANALYSIS_TOOLS:
367            if (applyTools is None) or (tool in applyTools):
368                if i == 0:
369                    columns.append(tool)
370                row.append(STEP_ANALYSIS_TOOLS[tool](situation))
371
372    stepwiseRows: List[Sequence[AnalysisResult]] = [
373        ['Per-decision-per-step, metrics (one table per metric):']
374    ]
375    # For each tool; one row per exploration step and one column per
376    # decision
377    decisionList = exploration.allDecisions()
378    columns = ['Step ↓/Decision →'] + decisionList
379    identities = ['Decision names:'] + [
380        analysis.lastIdentity(exploration, d)
381        for d in decisionList
382    ]
383    for tool in STEPWISE_DECISION_ANALYSIS_TOOLS:
384        if (applyTools is None) or (tool in applyTools):
385            stepwiseRows.append([tool])
386            stepwiseRows.append(columns)
387            stepwiseRows.append(identities)
388            for i, situation in enumerate(exploration):
389                row = [i]
390                stepwiseRows.append(row)
391                for decision in decisionList:
392                    row.append(
393                        STEPWISE_DECISION_ANALYSIS_TOOLS[tool](
394                            situation,
395                            decision
396                        )
397                    )
398
399    # Build a grid containing just the non-empty analysis categories, so
400    # that if you deselect some tools you get a smaller CSV file:
401    grid: List[Sequence[AnalysisResult]] = []
402    if len(wholeRows) > 1:
403        grid.extend(wholeRows)
404    for block in decisionRows, stepRows, stepwiseRows:
405        if len(block) > 1:
406            if grid:
407                grid.append([])  # spacer
408            grid.extend(block)
409
410    # Figure out our destination stream:
411    if destination is None:
412        outStream = sys.stdout
413        closeIt = False
414    else:
415        outStream = open(destination, 'w')
416        closeIt = True
417
418    # Create a CSV writer for our stream
419    writer = csv.writer(outStream)
420
421    # Write out our grid to the file
422    try:
423        writer.writerows(grid)
424    finally:
425        if closeIt:
426            outStream.close()
427
428
429def convert(
430    source: pathlib.Path,
431    destination: pathlib.Path,
432    inputFormatOverride: Optional[SourceType] = None,
433    outputFormatOverride: Optional[SourceType] = None,
434    step: int = -1
435) -> None:
436    """
437    Converts between exploration and graph formats. By default, formats
438    are determined by file extensions, but using the `--format` and
439    `--output-format` options can override this. The available formats
440    are:
441
442    - '.dcg' A `core.DecisionGraph` stored in JSON format.
443    - '.dot' A `core.DecisionGraph` stored as a GraphViz DOT file.
444    - '.exp' A `core.DiscreteExploration` stored in JSON format.
445    - '.exj' A `core.DiscreteExploration` stored as a journal (see
446        `journal.JournalObserver`; TODO: writing this format).
447
448    When converting a decision graph into an exploration format, the
449    resulting exploration will have a single starting step containing
450    the entire specified graph. When converting an exploration into a
451    decision graph format, only the current graph will be saved, unless
452    `--step` is used to specify a different step index to save.
453    """
454    # TODO journal writing
455    obj = loadSource(source, inputFormatOverride)
456
457    if outputFormatOverride is None:
458        outputFormat = determineFileType(str(destination))
459    else:
460        outputFormat = outputFormatOverride
461
462    if outputFormat in ("graph", "dot"):
463        if isinstance(obj, core.DiscreteExploration):
464            graph = obj.getSituation(step).graph
465        else:
466            graph = obj
467        if outputFormat == "graph":
468            saveDecisionGraph(destination, graph)
469        else:
470            saveDotFile(destination, graph)
471    else:
472        if isinstance(obj, core.DecisionGraph):
473            exploration = core.DiscreteExploration.fromGraph(obj)
474        else:
475            exploration = obj
476        if outputFormat == "exploration":
477            saveExploration(destination, exploration)
478        else:
479            saveAsJournal(destination, exploration)
480
481
482INSPECTOR_HELP = """
483Available commands:
484
485- 'help' or '?': List commands.
486- 'done', 'quit', 'q', or 'exit': Quit the inspector.
487- 'f' or 'follow': Follow the primary decision when changing steps. Also
488    changes to that decision immediately. Toggles off if on.
489- 'cd' or 'goto': Change focus decision to the named decision. Cancels
490    follow mode.
491- 'ls' or 'list' or 'destinations': Lists transitions at this decision
492    and their destinations, as well as any mechanisms at this decision.
493- 'lst' or 'steps': Lists each step of the exploration along with the
494    primary decision at each step.
495- 'st' or 'step': Switches to the specified step (an index)
496- 'n' or 'next': Switches to the next step.
497- 'p' or 'prev' or 'previous': Switches to the previous step.
498- 't' or 'take': Change focus decision to the decision which is the
499    destination of the specified transition at the current focused
500    decision.
501- 'prm' or 'primary': Displays the current primary decision.
502- 'a' or 'active': Lists all currently active decisions
503- 'u' or 'unexplored': Lists all unexplored transitions at the current
504    step.
505- 'x' or 'explorable': Lists all unexplored transitions at the current
506    step which are traversable based on the current state. (TODO:
507    make this more accurate).
508- 'r' or 'reachable': TODO
509- 'A' or 'all': Lists all decisions at the current step.
510- 'M' or 'mechanisms': Lists all mechanisms at the current step.
511"""
512
513
514def inspect(
515    source: pathlib.Path,
516    formatOverride: Optional[SourceType] = None
517) -> None:
518    """
519    Inspects the graph or exploration stored in the `source` file,
520    launching an interactive command line for inspecting properties of
521    decisions, transitions, and situations. The file extension is used
522    to determine how to load the data, although the `--format` option
523    may override this. '.dcg' files are assumed to be decision graphs in
524    JSON format, '.exp' files are assumed to be exploration objects in
525    JSON format, and '.exj' files are assumed to be exploration journals
526    in the default journal format. If the object that gets loaded is a
527    graph, a 1-step exploration containing just that graph will be
528    created to inspect. Inspector commands are listed in the
529    `INSPECTOR_HELP` variable.
530    """
531    print(f"Loading exploration from {source!r}...")
532    # Load our exploration
533    exploration = loadSource(source, formatOverride)
534    if isinstance(exploration, core.DecisionGraph):
535        exploration = core.DiscreteExploration.fromGraph(exploration)
536
537    print(
538        f"Inspecting exploration with {len(exploration)} step(s) and"
539        f" {len(exploration.allDecisions())} decision(s):"
540    )
541    print("('h' for help)")
542
543    # Set up tracking variables:
544    step = len(exploration) - 1
545    here: Optional[base.DecisionID] = exploration.primaryDecision(step)
546    graph = exploration.getSituation(step).graph
547    follow = True
548
549    pf = parsing.ParseFormat()
550
551    if here is None:
552        print("Note: There are no decisions in the final graph.")
553
554    while True:
555        # Re-establish the prompt
556        prompt = "> "
557        if here is not None and here in graph:
558            prompt = graph.identityOf(here) + "> "
559        elif here is not None:
560            prompt = f"{here} (?)> "
561
562        # Prompt for the next command
563        fullCommand = input(prompt).split()
564
565        # Track number of invalid commands so we can quit after 10 in a row
566        invalidCommands = 0
567
568        if len(fullCommand) == 0:
569            cmd = ''
570            args = ''
571        else:
572            cmd = fullCommand[0]
573            args = ' '.join(fullCommand[1:])
574
575        # Do what the command says
576        invalid = False
577        if cmd in ("help", '?'):
578            # Displays help message
579            if len(args.strip()) > 0:
580                print("(help does not accept any arguments)")
581            print(INSPECTOR_HELP)
582        elif cmd in ("done", "exit", "quit", "q"):
583            # Exits the inspector
584            if len(args.strip()) > 0:
585                print("(quit does not accept any arguments)")
586            print("Bye.")
587            break
588        elif cmd in ("f", "follow"):
589            if follow:
590                follow = False
591                print("Stopped following")
592            else:
593                follow = True
594                here = exploration.primaryDecision(step)
595                print(f"Now following at: {graph.identityOf(here)}")
596        elif cmd in ("cd", "goto"):
597            # Changes focus to a specific decision
598            try:
599                target = pf.parseDecisionSpecifier(args)
600                target = graph.resolveDecision(target)
601                here = target
602                follow = False
603                print(f"now at: {graph.identityOf(target)}")
604            except Exception:
605                print("(invalid decision specifier)")
606        elif cmd in ("ls", "list", "destinations"):
607            fromID: Optional[base.AnyDecisionSpecifier] = None
608            if args.strip():
609                fromID = pf.parseDecisionSpecifier(args)
610                fromID = graph.resolveDecision(fromID)
611            else:
612                fromID = here
613
614            if fromID is None:
615                print(
616                    "(no focus decision and no decision specified;"
617                    " nothing to list; use 'cd' to specify a decision,"
618                    " or 'all' to list all decisions)"
619                )
620            else:
621                outgoing = graph.destinationsFrom(fromID)
622                info = graph.identityOf(fromID)
623                if len(outgoing) > 0:
624                    print(f"Destinations from {info}:")
625                    print(graph.destinationsListing(outgoing))
626                else:
627                    print("No outgoing transitions from {info}.")
628        elif cmd in ("lst", "steps"):
629            total = len(exploration)
630            print(f"{total} step(s):")
631            for step in range(total):
632                pr = exploration.primaryDecision(step)
633                situ = exploration.getSituation(step)
634                stGraph = situ.graph
635                identity = stGraph.identityOf(pr)
636                print(f"  {step} at {identity}")
637            print(f"({total} total step(s))")
638        elif cmd in ("st", "step"):
639            stepTo = int(args.strip())
640            if stepTo < 0:
641                stepTo += len(exploration)
642            if stepTo < 0:
643                print(
644                    f"Invalid step {args!r} (too negative; min is"
645                    f" {-len(exploration)})"
646                )
647            if stepTo >= len(exploration):
648                print(
649                    f"Invalid step {args!r} (too large; max is"
650                    f" {len(exploration) - 1})"
651                )
652
653            step = stepTo
654            graph = exploration.getSituation(step).graph
655            if follow:
656                here = exploration.primaryDecision(step)
657                print(f"Followed to: {graph.identityOf(here)}")
658        elif cmd in ("n", "next"):
659            if step == -1 or step >= len(exploration) - 2:
660                print("Can't step beyond the last step.")
661            else:
662                step += 1
663                graph = exploration.getSituation(step).graph
664                if here not in graph:
665                    here = None
666            print(f"At step {step}")
667            if follow:
668                here = exploration.primaryDecision(step)
669                print(f"Followed to: {graph.identityOf(here)}")
670        elif cmd in ("p", "prev"):
671            if step == 0 or step <= -len(exploration) + 2:
672                print("Can't step before the first step.")
673            else:
674                step -= 1
675                graph = exploration.getSituation(step).graph
676                if here not in graph:
677                    here = None
678            print(f"At step {step}")
679            if follow:
680                here = exploration.primaryDecision(step)
681                print(f"Followed to: {graph.identityOf(here)}")
682        elif cmd in ("t", "take"):
683            if here is None:
684                print(
685                    "(no focus decision, so can't take transitions. Use"
686                    " 'cd' to specify a decision first.)"
687                )
688            else:
689                dest = graph.getDestination(here, args)
690                if dest is None:
691                    print(
692                        f"Invalid transition {args!r} (no destination for"
693                        f" that transition from {graph.identityOf(here)}"
694                    )
695                here = dest
696        elif cmd in ("prm", "primary"):
697            pr = exploration.primaryDecision(step)
698            if pr is None:
699                print("Step {step} has no primary decision")
700            else:
701                print(
702                    f"Primary decision for step {step} is:"
703                    f" {graph.identityOf(pr)}"
704                )
705        elif cmd in ("a", "active"):
706            active = exploration.getActiveDecisions(step)
707            print(f"Active decisions at step {step}:")
708            print(graph.namesListing(active))
709        elif cmd in ("u", "unexplored"):
710            unx = analysis.unexploredBranches(graph)
711            fin = ':' if len(unx) > 0 else '.'
712            print(f"{len(unx)} unexplored branch(es){fin}")
713            for frID, unTr in unx:
714                print(f"take {unTr} at {graph.identityOf(frID)}")
715        elif cmd in ("x", "explorable"):
716            ctx = base.genericContextForSituation(
717                exploration.getSituation(step)
718            )
719            unx = analysis.unexploredBranches(graph, ctx)
720            fin = ':' if len(unx) > 0 else '.'
721            print(f"{len(unx)} unexplored branch(es){fin}")
722            for frID, unTr in unx:
723                print(f"take {unTr} at {graph.identityOf(frID)}")
724        elif cmd in ("r", "reachable"):
725            print("TODO: Reachable does not work yet.")
726        elif cmd in ("A", "all"):
727            print(
728                f"There are {len(graph)} decision(s) at step {step}:"
729            )
730            for decision in graph.nodes():
731                print(f"  {graph.identityOf(decision)}")
732        elif cmd in ("M", "mechanisms"):
733            count = len(graph.mechanisms)
734            fin = ':' if count > 0 else '.'
735            print(
736                f"There are {count} mechanism(s) at step {step}{fin}"
737            )
738            for mID in graph.mechanisms:
739                where, name = graph.mechanisms[mID]
740                state = exploration.mechanismState(mID, step=step)
741                if where is None:
742                    print(f"  {name!r} (global) in state {state!r}")
743                else:
744                    info = graph.identityOf(where)
745                    print(f"  {name!r} at {info} in state {state!r}")
746        else:
747            invalid = True
748
749        if invalid:
750            if invalidCommands >= 10:
751                print("Too many invalid commands; exiting.")
752                break
753            else:
754                if invalidCommands >= 8:
755                    print("{invalidCommands} invalid commands so far,")
756                    print("inspector will stop after 10 invalid commands...")
757                print(f"Unknown command {cmd!r}...")
758                invalidCommands += 1
759                print(INSPECTOR_HELP)
760        else:
761            invalidCommands = 0
762
763
764#--------------#
765# Parser setup #
766#--------------#
767
768parser = argparse.ArgumentParser(
769    prog="python -m exploration",
770    description="""\
771Runs various commands for processing exploration graphs and journals,
772and for converting between them or displaying them in various formats.
773"""
774)
775subparsers = parser.add_subparsers(
776    title="commands",
777    description="The available commands are:",
778    help="use these with -h/--help for more details"
779)
780
781showParser = subparsers.add_parser(
782    'show',
783    help="show an exploration",
784    description=textwrap.dedent(str(show.__doc__)).strip()
785)
786showParser.set_defaults(run="show")
787showParser.add_argument(
788    "source",
789    type=pathlib.Path,
790    help="The file to load"
791)
792showParser.add_argument(
793    '-f',
794    "--format",
795    choices=get_args(SourceType),
796    help=(
797        "Which format the source file is in (normally that can be"
798        " determined from the file extension)."
799    )
800)
801showParser.add_argument(
802    '-s',
803    "--step",
804    type=int,
805    default=-1,
806    help="Which graph step to show (when loading an exploration)."
807)
808
809analyzeParser = subparsers.add_parser(
810    'analyze',
811    help="analyze an exploration",
812    description=textwrap.dedent(str(analyze.__doc__)).strip()
813)
814analyzeParser.set_defaults(run="analyze")
815analyzeParser.add_argument(
816    "source",
817    type=pathlib.Path,
818    help="The file holding the exploration to analyze"
819)
820analyzeParser.add_argument(
821    "destination",
822    default=None,
823    type=pathlib.Path,
824    help=(
825        "The file name where the output should be written (this file"
826        " will be overwritten without warning)."
827    )
828)
829analyzeParser.add_argument(
830    '-f',
831    "--format",
832    choices=get_args(SourceType),
833    help=(
834        "Which format the source file is in (normally that can be"
835        " determined from the file extension)."
836    )
837)
838
839convertParser = subparsers.add_parser(
840    'convert',
841    help="convert an exploration",
842    description=textwrap.dedent(str(convert.__doc__)).strip()
843)
844convertParser.set_defaults(run="convert")
845convertParser.add_argument(
846    "source",
847    type=pathlib.Path,
848    help="The file holding the graph or exploration to convert."
849)
850convertParser.add_argument(
851    "destination",
852    type=pathlib.Path,
853    help=(
854        "The file name where the output should be written (this file"
855        " will be overwritten without warning)."
856    )
857)
858convertParser.add_argument(
859    '-f',
860    "--format",
861    choices=get_args(SourceType),
862    help=(
863        "Which format the source file is in (normally that can be"
864        " determined from the file extension)."
865    )
866)
867convertParser.add_argument(
868    '-o',
869    "--output-format",
870    choices=get_args(SourceType),
871    help=(
872        "Which format the converted file should be saved as (normally"
873        " that is determined from the file extension)."
874    )
875)
876convertParser.add_argument(
877    '-s',
878    "--step",
879    type=int,
880    default=-1,
881    help=(
882        "Which graph step to save (when converting from an exploration"
883        " format to a graph format)."
884    )
885)
886
887if __name__ == "__main__":
888    options = parser.parse_args()
889    if options.run == "show":
890        show(
891            options.source,
892            formatOverride=options.format,
893            step=options.step
894        )
895    elif options.run == "analyze":
896        analyze(
897            options.source,
898            formatOverride=options.format,
899            destination=options.destination
900        )
901    elif options.run == "convert":
902        convert(
903            options.source,
904            options.destination,
905            inputFormatOverride=options.format,
906            outputFormatOverride=options.output_format,
907            step=options.step
908        )
909    else:
910        raise RuntimeError(
911            f"Invalid 'run' default value: '{options.run}'."
912        )