{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "14e56d73-10be-48be-8de2-a1f6c5372205",
   "metadata": {},
   "source": [
    "```{index} command line\n",
    "```\n",
    "\n",
    "(commandline)=\n",
    "\n",
    "# Command Line Introduction\n",
    "\n",
    "Sometimes we will be directing you to use a command window or terminal to\n",
    "compile and run\n",
    "C# programs.[^1]\n",
    "\n",
    "Reasons to use the command line:\n",
    "\n",
    "- The command line precedes the graphical user interface (GUI) used in\n",
    "  modern operating systems and provides a simpler interface for input and output\n",
    "  that is very flexible and powerful for *knowledgeable* users.\n",
    "\n",
    "  - Input comes from the keyboard as typed characters (no mouse processing).\n",
    "    Commands are only processed once you press {kbd}`Enter`.\n",
    "  - Output goes to the monitor as textual information (no window processing).\n",
    "  - In C# these input/output mechanisms are called Console processing.\n",
    "  - Input from and output to files is done in a very similar way, simplifying learning.\n",
    "\n",
    "- Many software development organizations use command line processing\n",
    "  to automate creating, compiling (“building”), and running or executing\n",
    "  software programs.\n",
    "\n",
    "  - Command line “scripts” can be created to automate routine tasks.\n",
    "  - Command line scripts are similar to C# and other computer programs.\n",
    "  - Serious software developers should be familiar with the command line.\n",
    "\n",
    "The most direct way to access the command line (often called a *command shell*):\n",
    "\n",
    "- On Windows, open **Windows Terminal** (search for it in the Start menu)\n",
    "  or use **PowerShell**.\n",
    "\n",
    "- On a Mac or Linux, open a **Terminal** window.\n",
    "\n",
    "Mac, Linux, and other Unix variants work basically the same once\n",
    "you get to a terminal, so we will only distinguish Windows and Mac/Linux.\n",
    "\n",
    "```{index} command line; paths\n",
    "```\n",
    "\n",
    "(navigating-directories)=\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e79f702",
   "metadata": {},
   "source": "## Navigating Directories\n\nFirst make sure you are familiar with {ref}`path-strings`.\n\nIn a command shell there is always a *current working directory*, usually\nshown in the prompt for the next command.\nWhen you open a terminal or command window you will see\na prompt that tells you what folder or directory the command shell has\nstarted in: If you directly open a terminal as in the previous section,\nin Windows this is typically C:\\Windows\\System32, and on\na Mac it is typically /Users/*yourLogin*.\n\nParticularly on windows, this is an annoying folder. There are several ways\nto get to a better location.\n\nIf you can get to a parent folder of a folder that you want in a Windows Explorer window\n(by right clicking on Start) or Mac Finder, there are shortcuts to opening a terminal\nso the current directory is one being one shown in the graphical window:\n\nWindows  \n1.  In Windows explorer navigate to the parent folder,\n    showing the folder you want as a subfolder.\n2.  Hold down the shift key and *right* click on the desired folder.\n    A popup menu appears.\n3.  Click on “Open a Command Window here”.\n\nMac  \n1.  In the Finder navigate to the parent folder,\n    showing the folder you want as a subfolder.\n2.  Hold down the control key and click on the desired folder.\n    A popup menu appears.\n3.  Click on the bottom item Services, to get a submenu.\n4.  In the submenu click on “New Terminal at Folder” (likely the bottom entry).\n\n```{index} command line; dir and ls\n```\n\nFiles in the current working directory can to referred to by their simple names,\ne.g., *myfile.txt*. You can list all the files in the directory with the simple\ncommand `dir` (short for directory) in Windows or `ls` (short for list) on a Mac.\n\nYou need to refer to files not in the current directory via a relative or absolute\npath name.\n\nAfter starting in one folder, you may well want to change the current folder\nwithout opening a new terminal window.\nYou will see below that you can change the current\ndirectory with the *cd* command.\n\nOn a Mac, the file system is unified in\none hierarchy. On Windows there may be several drives, and you need to start a\npath reference with a drive, like C:, if it is not the current drive.\n\nWhen you open a command window in Windows,\nyou are likely to want to get to\nyour home directory (where the Mac users start automatically).\n\nWindows users enter the command below (substituting your login ID)\nto get to your home directory:\n\n``` none\ncd C:\\Users\\yourLoginId\n```\n\nThe cd is short for “Change Directory”, changing the current directory.\n\n```{index} drive change on Windows\n```\n\n(drive-change)=\n\nWindows only:\nThe cd command does not work the way you are likely to think about it on\na Windows system with more than one drive (like C: and flash drive E: that you have\nplugged in). Windows remembers a *separate* current directory for each\n*separate* drive. It also *independently* remembers a *current drive*.\nYou do *not change the current drive* with the cd command.\nThe command to change the current drive is just the name of the\ndrive with a colon after it. For example the command\n\n``` none\nE:\n```\n\nsets the current drive to E:, and the active directory is the\ncurrent directory on E:.\n\nHowever, if the current drive is C:, and you enter the command\n\n``` none\ncd E:\\comp170\n```\n\nthen you change the current directory on E:, but *the current drive remains C:*.\n\nWe described above how you can use a Windows Explorer/Finder folder to\nopen a *new* terminal.\nIf you just want to change\ndirectory in an existing terminal, there is also a shortcut to copy a long\nfolder name, given a Windows Explorer/Finder folder:\n\nWindows\n\n- Depending on the setup of your options, in the address bar you may *not* see a clear\n  path with a drive and backslashes. In that case generally clicking to the right of any\n  directory in the path converts the view to the version we use on the\n  command line.\n- When you see a full absolute path, you can just note it and manually copy it,\n  or else select it all and copy it\n  and follow the instructions in {ref}`copypaste` to later\n  paste in the command window.\n- In any case click in the terminal window, type *cd* and a space, then\n  type or paste the path.\n- Of course, you can also go the other way – if you see the current\n  directory name in the Windows prompt, type that into an Explorer address\n  bar to see its contents in a GUI window.\n\nOn a Mac there is an easier shortcut:\n\n- Type *cd* and a *space* to start the command in the terminal\n- Locate the directory you want as a subfolder in the Finder\n  (not opening the directory).\n- Drag the directory icon to the terminal. The path gets pasted! Press return."
  },
  {
   "cell_type": "markdown",
   "id": "eec0d5c0",
   "metadata": {},
   "source": "## Common Commands\n\nThe command shell waits for you to type in a *command* (a\nshort name that the shell recognizes) followed by 0 or more *parameters*\nseparated by spaces (and Enter).\nNote that if a parameter contains spaces you must surround the\nparameter value with matching single or double quotes – you’ll see an\nexample later.\n\nWe are going to mention some of the simplest uses of basic commands. More\nadvanced documentation would include more options.\n\nSome commands are common between the Windows and Mac shells:\n\ndir (Windows) or ls (Mac)  \nto list all the files a in the current directory or a named directory.\n\n```{index} command line; cd\n```\n\ncd  \nstands for *Change Directory* – you can use this\ncommand to change the current working directory to a different one.\n\nYou can use this command to change to directories where your C#\nprogram source files are located, if different from the initial\ndirectory.\n\nOn Windows, suppose you created a directory C:\\COMP170\\hello; to\nchange to that, type *cd C:\\COMP170\\hello* and press Enter – the shell\nprompt will change to show this new directory location and programs like\n*dotnet* will be able to access files there, directly\nby name. If the Comp170 directory was you current directory, it would\nbe shorter to use relative paths and just `cd hello`. Remember if\nyou want a different Windows drive, you must first use a\n{ref}`drive change command <drive-change>`.\n\nOn a Mac absolute or relative paths work with `cd`.\nThere is no issue with drives.\n\nIf you included a space in one or more of the directory names, for\nexample C:\\IST 1551\\hello (a space between COMP and 170) you should\nenclose the path in quotes like: `cd \"C:\\\\IST 1551\\\\hello\"`\n\n**Mac Note**: if you type just *cd* and press Enter you will change back to\nyour home directory. There is also a shorthand name for your home\ndirectory in command paths: tilde (~), often shifted backquote on the\nkeyboard. Sorry,\nno such thing with Windows.\n\n```{index} command line; mkdir\n```\n\nmkdir  \nstands for make directory –\nyou can use *mkdir* to create a new empty directory in the current\ndirectory.\n\nFor example, on a Mac with current directory /Users/*YourLogin*,\ntype *mkdir hello* and press Enter – this will create a new directory\n/Users/*yourLogin*/hello if it did not exist before; you can now create\na C# source file in that directory and enter *cd hello* in the command shell.\n\nAn optional Windows abbreviation is *md*.\n\n```{index} command line; rmdir\n```\n\nrmdir  \nremoves an *empty* directory that you give as parameter, e.g.,\n\n``` none\nrmdir hello\n```\n\nOther useful commands, with different names for Windows and Mac,\nare listed next by generic function,\nwith general Windows syntax first and Mac second, and then\noften examples in the same order:\n\n```{index} command line; display file\n```\n\nDisplay the contents of a text file in the command window. The Unix/Mac\nname origin: a more complicated\nuse of cat is to con**cat**enate files.\n\ntype\n\n*textFileName*\n\ncat\n\n*textFileName*\n\n``` none\ntype my_program.cs\ncat my_program.cs\n```\n\n```{index} command line; copy file\n```\n\nMake a copy of a file. Caution: If the second file already exists,\nyou wipe out the original contents!\n\ncopy\n\n*originalFile*\n\n*copyName*\n\ncp\n\n*originalFile*\n\n*copyName*\n\n``` none\ncopy prog.cs prog_bak.cs\ncp prog.cs prog_bak.cs\n```\n\n```{index} command line; delete file\n```\n\nErase or remove a file:\n\nerase\n\n*fileToKill*\n\nrm\n\n*fileToKill*\n\n``` none\nerase poorAttempt.cs\nrm poorAttempt.cs\n```\n\nAnother Windows equivalent is `del` (short for delete).\n\n```{index} command line; help\n```\n\nWe have explained the simplest use of many of the commands above.\nMany modifiers are possible.\n\nHelp on a command:\n\nhelp\n\n*commandName*\n\n;\n\n*commandName*\n\n–help\n\nNote the double dash above: This\nsometimes works for concise help on a Mac while you can generally get\nan immensely detailed help overload on a Mac from\n\n> man *commandName*"
  },
  {
   "cell_type": "markdown",
   "id": "20b15250",
   "metadata": {},
   "source": "```{index} command line; scripts\n```\n\n## Scripts\n\nThis is not a subject of this course, but commands can be combined into\nscript files.\n\nScripting languages are in fact whole new specialized programming languages,\nthat include many of the types of\nprogramming statements found in C#."
  },
  {
   "cell_type": "markdown",
   "id": "da437e1c",
   "metadata": {},
   "source": "```{index} command line; copy and paste\n```\n\n(copypaste)=\n\n## Copy and Paste\n\nCopying or pasting with a Mac is is the same with a terminal as in other editing:\nUse the same Apple Command key with C or P, and you can select with the mouse.\n\nIn Windows it is more complicated when using a command window:\nYou can paste into the current command line by *right*\nclicking on the Command Window Title bar, and select edit and then paste.\n\nBy default\na Windows command window is not sensitive to the mouse.\nYou can change so that it is sensitive\nfor select and copy: Right click in the title bar, select defaults, and make sure\nthe check boxes under edit options are *all* checked.\n(The last two are explained in the next section.)\nClick OK. Then you can select with\nmouse and press Enter for the selection to be remembered in the copy buffer."
  },
  {
   "cell_type": "markdown",
   "id": "88b9a1a7",
   "metadata": {},
   "source": "```{index} command line; shortcuts\n```\n\n## Command Line Shortcuts\n\nBoth Mac and Windows (with the right options selected,\nlike the Windows check boxes in the last section), allow you to reduce typing:\n\nYou can bring back a previous command for the history of commands that are automatically\nremembered: Use the up and down arrows. This makes it very easy to run the same command\nagain, or to make slight edits.\n\nBoth Windows and OS-X can see what files are in any directory being referred to.\nIf you just start to type a file or folder name and then press the Tab key, both\nWindows and OS-X will do *file completion*\nto complete the name if there is no ambiguity. If there is ambiguity,\nthey work differently:\n\n- Windows will cycle through all the options as you keep\n  pressing Tab.\n- On the first tab OS-X will do nothing but give a sound if there is\n  ambiguity, but the second tab will list all the options. Then you need to type enough\n  more to disambiguate the meaning."
  },
  {
   "cell_type": "markdown",
   "id": "footnotes-1602",
   "metadata": {},
   "source": [
    "```{rubric} Footnotes\n",
    "```\n",
    "\n",
    "[^1] Thanks to Dr. Robert Yacobellis for elaborations to this section.\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}