'ralpha' help

Name:	ralpha
Version:	0.1
Last update:	2021-05-21 14:43:29

This file documents the command line tool ralpha provided by Alpha. Here ralpha stands for "remote alpha". This tool (written in bash syntax) lets you edit files or open new windows located on remote Unix machines as if they were local files. This is done through an ssh tunnel established between your local computer and the remote machine.
Technically the ralpha tool must be installed on the remote machine and communicates with Alpha via a socket as explained in the Alpha Server Help.
If you want to edit local files from a terminal window or from a shell script, you should rather use one of the alphaed or alphac tools.

How it works

The script can be found inside the application bundle in the $APPLICATION/Contents/Resources/Libraries/Extras folder. Here $APPLICATION designates the path of the Alpha application (click here to place the path in the Clipboard).
It is also distributed with Alpha's ExtraTools: click here to download the ExtraTools.
You must first copy the script on the remote machine where you want to edit files. When this is done, make sure it is executable. If this is not the case, type the following command in a Terminal window:

chmod a+x ralpha

Then you must connect to the remote machine with ssh. For this, you will need to know the port your Alpha application is listening on. To find out, you can open a Tcl shell and execute the alphaServer::port proc like this:

Welcome to Alpha's AlphaTcl shell.
«» alphaServer::port
50280

This command reports the port number (50280 in the previous example).
Note that, by default, Alpha uses port 51954. This hardwired value may be changed with the Alpha Server Port global preference found in the General Preferences panel. Note also that in the (unlikely) event where another process is already listening on the hardwired port, then Alpha finds another one randomly. The alphaServer::port proc used above will always report the actual value. See also the Environment variables section if you want to set the port's value in the remote shell.
Let us say that the remote server's address is remote.server.com. You can now connect to this server using a command like:

ssh -R 51954:localhost:51954 remote.server.com

The -R option sets up a reverse tunnel. The first 51954 designates a port on the remote machine. The localhost:51954 part designates the port on your local machine. If someone else is already using port 51954 on the server, choose another one. The ports do not have to be the same on the local and the remote machines.
You are now ready to test the mechanism. Note that Alpha has to be running for this to work. Just try a command like:

ralpha some_file.txt

where some_file.txt is a file located on the remote server. This opens a document window in Alpha on your local machine.
Make any changes you want to the file edited with Alpha and save it. As soon as you save it, the file contents are sent to the remote machine. You can check this on your server with the following command:

cat some_file.txt

The exact syntax of the ralpha tool is explained in the next section.

Usage

The general syntax of this script can take two forms:

ralpha [options] ?linespec? ?--? file
ralpha [options] ?linespec? -c ?--? name [string|-]

The first form is used to open an already existing file.
The second form, with the -c argument, is used to create a new file on the remote server. In this form, the optional last argument (after the name argument) may be

a string to form the initial contents of the file.
a dash '-' to read the initial contents from standard input. This allows to use ralpha in pipes.

Note that the -c argument may appear anywhere among the options.
Both forms of the command support the following options:

-d	print debugging information
-e enc	encoding (default UTF-8)
-f	force open (if not writable)
-h	print usage
-H str	connect to host (default localhost)
-m str	mode
-p num	port number to use for connection
-v	verbose
-V	print version
-w	wait
--	end of options

The optional -w (or -wait) argument makes ralpha wait for the edited window to be closed in Alpha.
The linespec argument lets you specify a region to hilite. The format is:

+line1[.col1][,line2[.col2]]

If .col1 is omitted, the selection will start at the beginning of line1. If .col2 is omitted, the selection will stop after the end of line2. If the second part of the line specification (line2[.col2]) is omitted, then it is equal to the first one. The linespec may appear anywhere among the options.
See the Examples section below.

Environment variables

It is possible to define environment variables in the remote shell to hold the host or the port number in order to avoid specifying the -H and -p options each time you edit a file with ralpha during an ssh session. These variables are named RALPHA_HOST and RALPHA_PORT respectively. Note that the option -p has precedence over these environment variables.
If neither the environment variables nor the -p option are set, then the script will use the default hardwired port 51954 defined by Alpha and will set the host to localhost.

Advanced options

The -p option lets you specify the port number on which the Alpha Server is listening. For more information, see the Alpha Server Help.
The -H option lets you specify the host's name. By default, this is localhost. If this option is set to auto, then the script will attempt to get the host's name from the SSH connection.
The -V options is meant for developers. It provides a more verbose output and debugging information.

Examples

To edit a file:

> ralpha some_file

To edit a file in TeX mode and in macRoman encoding:

> ralpha -m TeX -e macRoman some_file

To edit a file and select line 30:

> ralpha -s 30 some_file

To edit a file and select lines 30 to 34:

> ralpha -s 30,34 some_file

To edit a file and select from line 30 column 5 to line 34 column 10:

> ralpha -s 30.5,34.10 some_file

To open a file and wait until it is closed:

> ralpha -wait some_file

To create a new file called newname:

> ralpha -c newname

To create a new file with some text:

> ralpha -c newname "foo bar baz"

To create a new file with the contents of another file, use any of the following commands:

> ralpha -c newname - < /some/other/file
> cat /some/other/file | ralpha -c newname -

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2017-2021, Bernard Desgraupes.
All rights reserved.
The ralpha package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BERNARD DESGRAUPES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.