Home | Arachnophilia | Documentation |     Share This Page
Working with external programs
Arachnophilia is © Copyright 2011, P. Lutus.

Arachnophilia is CareWare

To understand this page, readers should be familiar with The Arachnophilia Macro Architecture — the features to be described assume some familiarity with the macro system.

General-Purpose Input-Output

These features were introduced in Arachnophilia Version 5.5.

The functions described in this section can be used to interact with your operating system and any programs that run under it. One of the functions reads a program's output, while the other passes the current Arachnophilia document or selection to a program for processing.

  • SystemCom

    SystemCom executes a system commmand/program and inserts the result into the current document. In the Arachnophilia macro editor, an example might look like this:

    Linux example:   [SystemCom:date]
    Windows example: [SystemCom:date /T]
                      

    This example queries the operating system for the current date and time on Linux (just the date on Windows), and inserts it into the current document at the location of the editing cursor.

    It's important to emphasize that any system command or program, including programs or scripts written by the user, can be used with this command. Here's another example:

    Linux example:   [SystemCom:ls -la (path)]
    Windows example: [SystemCom:dir (path)]
                      

    In this example, a directory listing is acquired for a given (path) and the result is inserted into the document.

  • SystemProcess

    SystemProcess takes the above to a higher level — it reads the current document/selection, streams it to an external program for processing, and inserts the result into the document at the editing position. This is a very powerful feature, and the explanation is a bit more involved.

    Here's an example — we will use a short Python script that converts streamed text to UPPERCASE, just to show how the feature works. Here's the Python script listing:

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    import sys
    
    for line in sys.stdin.readlines():
      line = line.upper()
      sys.stdout.write(line)
      
                      

    The above script may serve as a template for any similar text processing the reader might care to perform, using any desired text-processing rules (and any other scripting language preferred by the reader).

    To use this script (or another like it), one would create an Arachnophilia macro like this (using these instructions as a guide):

    [SystemProcess:path/to/script/name.py]
                      

    Then one might create a toolbar button or menu entry to activate this macro in a convenient way. When this macro is activated, Arachnophilia acquires the current document or selection text and streams it to the Python script. The python script processes the text and returns it to Arachnophilia, where it's inserted into the document.

    Remember about the Arachnophilia macro system that, if no document selection is made, the entire document's text is provided to the macro and is entirely replaced by the result, but if a selection is made, only the selection is changed by the macro.

The difference between SystemCom and SystemProcess is that the former command doesn't deliver the document's text to the external program, while the latter does. Be sure you're using the right command for the desired outcome:

  • SystemCom won't disturb your document's text (unless a selection has been made), it just inserts a program's output at the editing cursor.
  • SystemProcess takes the document's entire content or selection and replaces it with the external program's output.
  • In all cases, if you get an undesired result, just click the Undo toolbar button to recover.
Compiler-specific Functions
The features to be described next are most often used with compilers, but any program can be activated by, and can interact with, Arachnophilia.

For compiler-related activities, program activation uses one of two system macros, depending on the requirements:
  • The first is more suited to compilers that might return error messages. [SystemExec:arg] causes a named program to be launched with optional additional arguments. Here is a typical macro text for this command:

    [Save][SystemExec:g++ [FileName]]
    In this macro, the displayed file is saved to its already established storage location, then a popular C++ compiler is launched with the file's name as an argument (remember that Arachnophilia macros can be nested within other Arachnophilia macros). If the compiler produces any error messages, they will be listed at the bottom of the document panel, and the document's editing cursor will automatically be placed on the first reported error line. Like this:

    The above macro would be used for interactive programming — after some changes to the source file, the operator would simply activate this macro with a keystroke. If any errors were reported, they could be corrected interactively (the "feedback panel" shown in the image above can be clicked to move to each error in turn) and the macro could be activated again.

  • Another command -- [SystemConsole:arg] — is more suitable when some interaction with a program is anticipated, and a terminal window is needed. Here are example macros:

    Linux example:  [SystemConsole:bash -i]      
    Windows example [SystemConsole:cmd /k]
    
    These commands launch shell interpreters on the respective platforms, using a simple interactive terminal, launched in a separate window, to handle I/O.

It's unfortunate that these two compiler-related macros have names that are so similar to the newer ones described in the first section, but these two were written years ago, and I decided against renaming them because this might break existing user macros.

 

Home | Arachnophilia | Documentation |     Share This Page