new repository

1 files changed, 202 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fcmd.html b/devdocs/python~3.12/library%2Fcmd.html
new file mode 100644
index 00000000..cb29a143
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fcmd.html
@@ -0,0 +1,202 @@
+ <span id="cmd-support-for-line-oriented-command-interpreters"></span><h1>cmd — Support for line-oriented command interpreters</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/cmd.py">Lib/cmd.py</a></p>  <p>The <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> class provides a simple framework for writing line-oriented command interpreters. These are often useful for test harnesses, administrative tools, and prototypes that will later be wrapped in a more sophisticated interface.</p> <dl class="py class"> <dt class="sig sig-object py" id="cmd.Cmd">
+<code>class cmd.Cmd(completekey='tab', stdin=None, stdout=None)</code> </dt> <dd>
+<p>A <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> instance or subclass instance is a line-oriented interpreter framework. There is no good reason to instantiate <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> itself; rather, it’s useful as a superclass of an interpreter class you define yourself in order to inherit <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a>’s methods and encapsulate action methods.</p> <p>The optional argument <em>completekey</em> is the <a class="reference internal" href="readline#module-readline" title="readline: GNU readline support for Python. (Unix)"><code>readline</code></a> name of a completion key; it defaults to <kbd class="kbd docutils literal notranslate">Tab</kbd>. If <em>completekey</em> is not <a class="reference internal" href="constants#None" title="None"><code>None</code></a> and <a class="reference internal" href="readline#module-readline" title="readline: GNU readline support for Python. (Unix)"><code>readline</code></a> is available, command completion is done automatically.</p> <p>The optional arguments <em>stdin</em> and <em>stdout</em> specify the input and output file objects that the Cmd instance or subclass instance will use for input and output. If not specified, they will default to <a class="reference internal" href="sys#sys.stdin" title="sys.stdin"><code>sys.stdin</code></a> and <a class="reference internal" href="sys#sys.stdout" title="sys.stdout"><code>sys.stdout</code></a>.</p> <p>If you want a given <em>stdin</em> to be used, make sure to set the instance’s <a class="reference internal" href="#cmd.Cmd.use_rawinput" title="cmd.Cmd.use_rawinput"><code>use_rawinput</code></a> attribute to <code>False</code>, otherwise <em>stdin</em> will be ignored.</p> </dd>
+</dl> <section id="cmd-objects"> <span id="id1"></span><h2>Cmd Objects</h2> <p>A <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> instance has the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.cmdloop">
+<code>Cmd.cmdloop(intro=None)</code> </dt> <dd>
+<p>Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of the line as argument.</p> <p>The optional argument is a banner or intro string to be issued before the first prompt (this overrides the <a class="reference internal" href="#cmd.Cmd.intro" title="cmd.Cmd.intro"><code>intro</code></a> class attribute).</p> <p>If the <a class="reference internal" href="readline#module-readline" title="readline: GNU readline support for Python. (Unix)"><code>readline</code></a> module is loaded, input will automatically inherit <strong class="program">bash</strong>-like history-list editing (e.g. <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">P</kbd></kbd> scrolls back to the last command, <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">N</kbd></kbd> forward to the next one, <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">F</kbd></kbd> moves the cursor to the right non-destructively, <kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">B</kbd></kbd> moves the cursor to the left non-destructively, etc.).</p> <p>An end-of-file on input is passed back as the string <code>'EOF'</code>.</p> <p id="index-0">An interpreter instance will recognize a command name <code>foo</code> if and only if it has a method <code>do_foo()</code>. As a special case, a line beginning with the character <code>'?'</code> is dispatched to the method <a class="reference internal" href="#cmd.Cmd.do_help" title="cmd.Cmd.do_help"><code>do_help()</code></a>. As another special case, a line beginning with the character <code>'!'</code> is dispatched to the method <code>do_shell()</code> (if such a method is defined).</p> <p>This method will return when the <a class="reference internal" href="#cmd.Cmd.postcmd" title="cmd.Cmd.postcmd"><code>postcmd()</code></a> method returns a true value. The <em>stop</em> argument to <a class="reference internal" href="#cmd.Cmd.postcmd" title="cmd.Cmd.postcmd"><code>postcmd()</code></a> is the return value from the command’s corresponding <code>do_*()</code> method.</p> <p>If completion is enabled, completing commands will be done automatically, and completing of commands args is done by calling <code>complete_foo()</code> with arguments <em>text</em>, <em>line</em>, <em>begidx</em>, and <em>endidx</em>. <em>text</em> is the string prefix we are attempting to match: all returned matches must begin with it. <em>line</em> is the current input line with leading whitespace removed, <em>begidx</em> and <em>endidx</em> are the beginning and ending indexes of the prefix text, which could be used to provide different completion depending upon which position the argument is in.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.do_help">
+<code>Cmd.do_help(arg)</code> </dt> <dd>
+<p>All subclasses of <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> inherit a predefined <code>do_help()</code>. This method, called with an argument <code>'bar'</code>, invokes the corresponding method <code>help_bar()</code>, and if that is not present, prints the docstring of <code>do_bar()</code>, if available. With no argument, <code>do_help()</code> lists all available help topics (that is, all commands with corresponding <code>help_*()</code> methods or commands that have docstrings), and also lists any undocumented commands.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.onecmd">
+<code>Cmd.onecmd(str)</code> </dt> <dd>
+<p>Interpret the argument as though it had been typed in response to the prompt. This may be overridden, but should not normally need to be; see the <a class="reference internal" href="#cmd.Cmd.precmd" title="cmd.Cmd.precmd"><code>precmd()</code></a> and <a class="reference internal" href="#cmd.Cmd.postcmd" title="cmd.Cmd.postcmd"><code>postcmd()</code></a> methods for useful execution hooks. The return value is a flag indicating whether interpretation of commands by the interpreter should stop. If there is a <code>do_*()</code> method for the command <em>str</em>, the return value of that method is returned, otherwise the return value from the <a class="reference internal" href="#cmd.Cmd.default" title="cmd.Cmd.default"><code>default()</code></a> method is returned.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.emptyline">
+<code>Cmd.emptyline()</code> </dt> <dd>
+<p>Method called when an empty line is entered in response to the prompt. If this method is not overridden, it repeats the last nonempty command entered.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.default">
+<code>Cmd.default(line)</code> </dt> <dd>
+<p>Method called on an input line when the command prefix is not recognized. If this method is not overridden, it prints an error message and returns.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.completedefault">
+<code>Cmd.completedefault(text, line, begidx, endidx)</code> </dt> <dd>
+<p>Method called to complete an input line when no command-specific <code>complete_*()</code> method is available. By default, it returns an empty list.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.columnize">
+<code>Cmd.columnize(list, displaywidth=80)</code> </dt> <dd>
+<p>Method called to display a list of strings as a compact set of columns. Each column is only as wide as necessary. Columns are separated by two spaces for readability.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.precmd">
+<code>Cmd.precmd(line)</code> </dt> <dd>
+<p>Hook method executed just before the command line <em>line</em> is interpreted, but after the input prompt is generated and issued. This method is a stub in <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a>; it exists to be overridden by subclasses. The return value is used as the command which will be executed by the <a class="reference internal" href="#cmd.Cmd.onecmd" title="cmd.Cmd.onecmd"><code>onecmd()</code></a> method; the <a class="reference internal" href="#cmd.Cmd.precmd" title="cmd.Cmd.precmd"><code>precmd()</code></a> implementation may re-write the command or simply return <em>line</em> unchanged.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.postcmd">
+<code>Cmd.postcmd(stop, line)</code> </dt> <dd>
+<p>Hook method executed just after a command dispatch is finished. This method is a stub in <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a>; it exists to be overridden by subclasses. <em>line</em> is the command line which was executed, and <em>stop</em> is a flag which indicates whether execution will be terminated after the call to <a class="reference internal" href="#cmd.Cmd.postcmd" title="cmd.Cmd.postcmd"><code>postcmd()</code></a>; this will be the return value of the <a class="reference internal" href="#cmd.Cmd.onecmd" title="cmd.Cmd.onecmd"><code>onecmd()</code></a> method. The return value of this method will be used as the new value for the internal flag which corresponds to <em>stop</em>; returning false will cause interpretation to continue.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.preloop">
+<code>Cmd.preloop()</code> </dt> <dd>
+<p>Hook method executed once when <a class="reference internal" href="#cmd.Cmd.cmdloop" title="cmd.Cmd.cmdloop"><code>cmdloop()</code></a> is called. This method is a stub in <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a>; it exists to be overridden by subclasses.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="cmd.Cmd.postloop">
+<code>Cmd.postloop()</code> </dt> <dd>
+<p>Hook method executed once when <a class="reference internal" href="#cmd.Cmd.cmdloop" title="cmd.Cmd.cmdloop"><code>cmdloop()</code></a> is about to return. This method is a stub in <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a>; it exists to be overridden by subclasses.</p> </dd>
+</dl> <p>Instances of <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> subclasses have some public instance variables:</p> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.prompt">
+<code>Cmd.prompt</code> </dt> <dd>
+<p>The prompt issued to solicit input.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.identchars">
+<code>Cmd.identchars</code> </dt> <dd>
+<p>The string of characters accepted for the command prefix.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.lastcmd">
+<code>Cmd.lastcmd</code> </dt> <dd>
+<p>The last nonempty command prefix seen.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.cmdqueue">
+<code>Cmd.cmdqueue</code> </dt> <dd>
+<p>A list of queued input lines. The cmdqueue list is checked in <a class="reference internal" href="#cmd.Cmd.cmdloop" title="cmd.Cmd.cmdloop"><code>cmdloop()</code></a> when new input is needed; if it is nonempty, its elements will be processed in order, as if entered at the prompt.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.intro">
+<code>Cmd.intro</code> </dt> <dd>
+<p>A string to issue as an intro or banner. May be overridden by giving the <a class="reference internal" href="#cmd.Cmd.cmdloop" title="cmd.Cmd.cmdloop"><code>cmdloop()</code></a> method an argument.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.doc_header">
+<code>Cmd.doc_header</code> </dt> <dd>
+<p>The header to issue if the help output has a section for documented commands.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.misc_header">
+<code>Cmd.misc_header</code> </dt> <dd>
+<p>The header to issue if the help output has a section for miscellaneous help topics (that is, there are <code>help_*()</code> methods without corresponding <code>do_*()</code> methods).</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.undoc_header">
+<code>Cmd.undoc_header</code> </dt> <dd>
+<p>The header to issue if the help output has a section for undocumented commands (that is, there are <code>do_*()</code> methods without corresponding <code>help_*()</code> methods).</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.ruler">
+<code>Cmd.ruler</code> </dt> <dd>
+<p>The character used to draw separator lines under the help-message headers. If empty, no ruler line is drawn. It defaults to <code>'='</code>.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="cmd.Cmd.use_rawinput">
+<code>Cmd.use_rawinput</code> </dt> <dd>
+<p>A flag, defaulting to true. If true, <a class="reference internal" href="#cmd.Cmd.cmdloop" title="cmd.Cmd.cmdloop"><code>cmdloop()</code></a> uses <a class="reference internal" href="functions#input" title="input"><code>input()</code></a> to display a prompt and read the next command; if false, <a class="reference internal" href="sys#sys.stdout" title="sys.stdout"><code>sys.stdout.write()</code></a> and <a class="reference internal" href="sys#sys.stdin" title="sys.stdin"><code>sys.stdin.readline()</code></a> are used. (This means that by importing <a class="reference internal" href="readline#module-readline" title="readline: GNU readline support for Python. (Unix)"><code>readline</code></a>, on systems that support it, the interpreter will automatically support <strong class="program">Emacs</strong>-like line editing and command-history keystrokes.)</p> </dd>
+</dl> </section> <section id="cmd-example"> <span id="id2"></span><h2>Cmd Example</h2> <p>The <a class="reference internal" href="#module-cmd" title="cmd: Build line-oriented command interpreters."><code>cmd</code></a> module is mainly useful for building custom shells that let a user work with a program interactively.</p> <p>This section presents a simple example of how to build a shell around a few of the commands in the <a class="reference internal" href="turtle#module-turtle" title="turtle: An educational framework for simple graphics applications"><code>turtle</code></a> module.</p> <p>Basic turtle commands such as <a class="reference internal" href="turtle#turtle.forward" title="turtle.forward"><code>forward()</code></a> are added to a <a class="reference internal" href="#cmd.Cmd" title="cmd.Cmd"><code>Cmd</code></a> subclass with method named <code>do_forward()</code>. The argument is converted to a number and dispatched to the turtle module. The docstring is used in the help utility provided by the shell.</p> <p>The example also includes a basic record and playback facility implemented with the <a class="reference internal" href="#cmd.Cmd.precmd" title="cmd.Cmd.precmd"><code>precmd()</code></a> method which is responsible for converting the input to lowercase and writing the commands to a file. The <code>do_playback()</code> method reads the file and adds the recorded commands to the <a class="reference internal" href="#cmd.Cmd.cmdqueue" title="cmd.Cmd.cmdqueue"><code>cmdqueue</code></a> for immediate playback:</p> <pre data-language="python">import cmd, sys
+from turtle import *
+
+class TurtleShell(cmd.Cmd):
+    intro = 'Welcome to the turtle shell.   Type help or ? to list commands.\n'
+    prompt = '(turtle) '
+    file = None
+
+    # ----- basic turtle commands -----
+    def do_forward(self, arg):
+        'Move the turtle forward by the specified distance:  FORWARD 10'
+        forward(*parse(arg))
+    def do_right(self, arg):
+        'Turn turtle right by given number of degrees:  RIGHT 20'
+        right(*parse(arg))
+    def do_left(self, arg):
+        'Turn turtle left by given number of degrees:  LEFT 90'
+        left(*parse(arg))
+    def do_goto(self, arg):
+        'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
+        goto(*parse(arg))
+    def do_home(self, arg):
+        'Return turtle to the home position:  HOME'
+        home()
+    def do_circle(self, arg):
+        'Draw circle with given radius an options extent and steps:  CIRCLE 50'
+        circle(*parse(arg))
+    def do_position(self, arg):
+        'Print the current turtle position:  POSITION'
+        print('Current position is %d %d\n' % position())
+    def do_heading(self, arg):
+        'Print the current turtle heading in degrees:  HEADING'
+        print('Current heading is %d\n' % (heading(),))
+    def do_color(self, arg):
+        'Set the color:  COLOR BLUE'
+        color(arg.lower())
+    def do_undo(self, arg):
+        'Undo (repeatedly) the last turtle action(s):  UNDO'
+    def do_reset(self, arg):
+        'Clear the screen and return turtle to center:  RESET'
+        reset()
+    def do_bye(self, arg):
+        'Stop recording, close the turtle window, and exit:  BYE'
+        print('Thank you for using Turtle')
+        self.close()
+        bye()
+        return True
+
+    # ----- record and playback -----
+    def do_record(self, arg):
+        'Save future commands to filename:  RECORD rose.cmd'
+        self.file = open(arg, 'w')
+    def do_playback(self, arg):
+        'Playback commands from a file:  PLAYBACK rose.cmd'
+        self.close()
+        with open(arg) as f:
+            self.cmdqueue.extend(f.read().splitlines())
+    def precmd(self, line):
+        line = line.lower()
+        if self.file and 'playback' not in line:
+            print(line, file=self.file)
+        return line
+    def close(self):
+        if self.file:
+            self.file.close()
+            self.file = None
+
+def parse(arg):
+    'Convert a series of zero or more numbers to an argument tuple'
+    return tuple(map(int, arg.split()))
+
+if __name__ == '__main__':
+    TurtleShell().cmdloop()
+</pre> <p>Here is a sample session with the turtle shell showing the help functions, using blank lines to repeat commands, and the simple record and playback facility:</p> <pre data-language="none">Welcome to the turtle shell.   Type help or ? to list commands.
+
+(turtle) ?
+
+Documented commands (type help &lt;topic&gt;):
+========================================
+bye     color    goto     home  playback  record  right
+circle  forward  heading  left  position  reset   undo
+
+(turtle) help forward
+Move the turtle forward by the specified distance:  FORWARD 10
+(turtle) record spiral.cmd
+(turtle) position
+Current position is 0 0
+
+(turtle) heading
+Current heading is 0
+
+(turtle) reset
+(turtle) circle 20
+(turtle) right 30
+(turtle) circle 40
+(turtle) right 30
+(turtle) circle 60
+(turtle) right 30
+(turtle) circle 80
+(turtle) right 30
+(turtle) circle 100
+(turtle) right 30
+(turtle) circle 120
+(turtle) right 30
+(turtle) circle 120
+(turtle) heading
+Current heading is 180
+
+(turtle) forward 100
+(turtle)
+(turtle) right 90
+(turtle) forward 100
+(turtle)
+(turtle) right 90
+(turtle) forward 400
+(turtle) right 90
+(turtle) forward 500
+(turtle) right 90
+(turtle) forward 400
+(turtle) right 90
+(turtle) forward 300
+(turtle) playback spiral.cmd
+Current position is 0 0
+
+Current heading is 0
+
+Current heading is 180
+
+(turtle) bye
+Thank you for using Turtle
+</pre> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/cmd.html" class="_attribution-link">https://docs.python.org/3.12/library/cmd.html</a>
+  </p>
+</div>