Skip to content

Latest commit

 

History

History
179 lines (155 loc) · 9.97 KB

INSTRUCTIONS.md

File metadata and controls

179 lines (155 loc) · 9.97 KB

Dependencies:

  • Python 3
  • PyQt6 version 6.3.1 (or higher) or PyQt5 version 5.7 (or higher) or PyQt4 version 4.10 (or higher)
  • QScintilla 2.9 or higher (is bundled in the PyQt installer on Windows)
  • psutil (required for the new process monitor)
  • pywin32 (required on Windows only)

Optional dependencies:

  • XTerm terminal editor is used by default on Linux (can be changed in the config file)
  • Cython (ONLY FOR BUILDING SPECIAL LEXERS)
  • Nim programming language (ONLY FOR BUILDING SPECIAL LEXERS)
  • Universal or Exuberant Ctags (Used with code tree displaying)

Installation notes:

  • Windows:
    Method 1 - using the official PyQt installer:
    Install the latest PyQt4 or PyQt5 or PyQt6 library for your version of Python3 (QScintilla2 is bundled with the installer). Run Ex.Co. using the command described below in the 'Starting Ex.Co.' section.

    Method 2 - using pip:
    If you have pip installed with your Python 3 installation (needs to be Python 3.5 or higher), you can install PyQt5 and QScintilla with the following commands (You will need to run the commands as administrator!):

$ pip install PyQt5
$ pip install Qscintilla
$ pip install psutil
$ pip install pywin32

  • GNU/Linux:
    Method 1 - using apt-get:
    If you are on Lubuntu, Raspbian or probably most Debian derivatives, install the following libraries using apt-get:

    • python3.x (Probably already installed on the system)
    • python3-pyqt4 or python3-pyqt5
    • python3-pyqt4.qsci or python3-pyqt5.qsci (If this library is outdated, you will get a 'missing QsciLexerCoffeeScript' or similar exception. Update the repositories and try again. If that still doesn't help, try using Ubuntu's 'Universe' repositories.)

    Method 2 - using pip:
    If you have pip installed with your Python 3 installation (needs to be Python 3.5 or higher) , you can install PyQt5 and QScintilla with the following commands (You will need to run the commands as sudo!):

$ pip install PyQt5
$ pip install Qscintilla
$ pip install psutil

Otherwise you can install PyQt4/PyQt5 and QScintilla (you'll also need the SIP library) from source from their official website. Download the source code and follow the instructions in the readme/install files. You'll also need the Qt C++ source code.

  • Mac OS:
    Try using Anaconda Python 3 and it's package manager to install all dependencies. Here is the more information.
    I don't know much about Mac's, but you can try using the default Mac package manager to find the PyQt4 and QScintilla libraries or install the libraries from source, same as on GNU/Linux.

Starting Ex.Co.:

On Windows and GNU/Linux where Python 3 is the default interpreter, use the shell/command-line command:

$ python exco.py

On GNU/Linux with Python 3 as the non-default interpreter, use the shell/command-line command:

$ python3 exco.py

For more startup options add the --help or -h flag.

Quick examples:

1. Basic text manipulation with the REPL (very detailed example):

  • start Ex.Co. by executing python main.py
  • focus the main editor window (the big one) with one of the following options:
    • click on it the mouse
    • press Ctrl+1
    • use the menubar by selecting View -> Focus Main Window
    • use the 'Function Wheel' by pressing F1 and selection the Focus Main Window icon
  • create a new document with one of the following options:
    • pressing Ctrl+N
    • use the menubar by selecting File -> New
    • use the 'Function Wheel' by pressing F1 and selection the Create New Document icon
  • focus the single-line REPL one of the following options:
    • click on it with the mouse
    • press Ctrl+R
    • use the menubar by selecting REPL -> Focus REPL(Single)
    • use the 'Function Wheel' by pressing F1 and selection the REPL Focus (Single Line) icon
  • write line_list = ["one", "two", "three"] and press Enter
  • the main editor window should now contain the three new lines with each line containing the text from the corresponding line_list position
  • line_list is a shorthand for cmain.line_list, the same can be done with cupper.line_list for the upper window and clower.line_list for the lower window
  • NOTES:
    • All commands in the REPL must be valid Python 3 code!
    • line_list is implemented as a python list so most list operations apply to it: append, insert, sort, ...

2. Manipulate editor lines using the REPL:

  • create a new document in the main editor window (look at previous example for details)
  • focus the REPL (Ctrl+R)
  • write line_list.append("My new line!") and press Enter
    • A new line was inserted into the new document
  • while the REPL is still focused, press the UP arrow to scroll up one level to the last command. As soon as you press UP the command line_list.append("My new line!") should be visible in again and press Enter
  • press F3 to execute the 'last executed REPL command' again
    • now there should be three 'My new line!' lines in the new document
  • write line_list[1] = "Changed line one" and press Enter
    • the first line in the new document should now read Changed line one
  • try the same with line_list[2] and line_list[3]
  • write line_list.insert(2, "Inserted line") and press Enter
    • the second line 'Inserted line' was inserted
  • write line_list.sort() and press Enter
    • the lines in the new document should now be sorted alphabetically
  • focus the multi-line REPL (Ctrl+5)
  • write the text below into the multi-line REPL and press Ctrl+Enter: 
          for i in range(10):
          line_list.append(str(i))
    • ten new lines were added, from "0" to "9"

3. Text diffing example:

  • open the first text document in the main editor window by first focusing the main window and pressing Ctrl+O
  • find and open the file using the popup dialog
  • open another document using the same two steps as above
  • now that the second document is selected and visible, move the mouse to the first documents tab and right click on it
  • a popup menu will be displayed and select the Text diff to main window option
  • The diff will be displayed in a newly created tab in the main editor window called DIFF('document_name_1'/document_name_2)
  • the REPL MESSAGES tab will display the diff detailes
  • when the DIFF tab is selected, you can use the helper buttons in the upper right corner of the main editor window:
    • blue button: got to the next unique line in document 1
    • purple button: got to the next unique line in document 2
    • green button: got to the next similar line

4. Moving tabs from window to window:

  • focus the main editor window
  • create a new document (Ctrl+N)
  • press Shift and left click-and-hold on the new documents tab
  • drag the mouse into the upper editor window and release the left mouse button
  • the document has now moved to the upper editor window
  • Copying is the same except you hold down the Ctrl button

5. Adding your custom Python functions:

  • open the user_functions file by:
    • use the menubar by selecting File -> Edit User Functions
    • use the 'Function Wheel' by pressing F1 and selection the Edit User Functions icon
  • the user_functions file will open in the main editor window
  • add your Python (Python 3) function to the file and add the custom autocompletion for the function:
  • Example: 
        def my_custom_function():
        # custom function code
    my_custom_function.autocompletion = 'my_custom_function()'
  • save the file with one of the following options:
    • press Ctrl+S
    • use the menubar by selecting File -> Save
    • use the 'Function Wheel' by pressing F1 and selection the Save icon
  • reload user functions with one of the following options:
    • use the menubar by selecting File -> Reload User Functions
    • use the 'Function Wheel' by pressing F1 and selection the Reload User Functions icon
  • try your newly added function by focusing the REPL (Ctrl+R) and start typing the name of your added function, it should automatically add the rest of the function text into the REPL
  • NOTE:
    • if your function name is similar to another already defined function, press Tab to scroll through all of the similar named function until you reach the newly added one

6. Run a terminal/shell command from Ex.Co.:

  • focus the REPL (Ctrl+R)
  • select the run command with one of the following options:
    • use the menubar by selecting System -> Run command
    • use the 'Function Wheel' by pressing F1 and selection the Run Console Command icon
  • the REPL should now have the text run("",show_console=True) in it
  • run the command like dir by entering it into the REPL text: run("dir",show_console=True) and press Enter
  • a new terminal window will popup and show the output of the dir command
  • NOTE:
    • insted of the menubar or function wheel shortcuts, you can also use the shorthand for running terminal commands with the REPL command rc: . The above example using the shorthand would be: rc: dir (note that there should be no quotes or double-quotes)



Todo:

  • add a curses version of Ex.Co. (only an idea at the moment)