Examples — Basic

✎ Quills

Last updated: 

The Quills API is currently very simple.  It is nevertheless possible to do some powerful things through Python in MacTelnet 4:

Initializing MacTelnet

Call Base.all_init() to initialize every C++ module in the framework.  Currently, there is no option to initialize fewer modules.

You should call this API before using Quills in your script, as not all modules can initialize just-in-time.

While MacTelnet 4 remains in beta, this call is somewhat “noisy” (it can generate text to the console), however the final design will write nothing by default and have an option to be verbose.

Tearing Down MacTelnet

When finished with Quills (at the end of your script), call Base.all_done() to tear down the framework.  Strictly speaking this is not necessary but it is a good idea.

Creating Sessions

The Session object in the Quills API represents access to resources, which is currently limited to one Unix command per terminal window.

Constructing a Session opens a new terminal window and runs its command.  (How this window behaves is currently subject to user preferences and cannot be set programmatically.)

The constructor requires an array, which contains all the command line words.  If you wish to express the command as a Python string, you can always split the string on whitespace.

Example:

	session_1 = Session(["progname", "-arg1", "-arg2", "-arg3", "val3", "-arg4", "val4"])
	session_2 = Session("progname -arg1 -arg2 -arg3 val3 -arg4 val4".split())

The returned object currently has no purpose.

If you were to place this type of statement in the MacTelnet front-end script, then your Unix command would run every time you launch MacTelnet.

Triggering Callbacks when Sessions Open

The Session module has the on_new_call() method for registering a callback that is told whenever any new session is created.  For example, you could do the following:

	def my_py_func():
		print "I was called by MacTelnet!"
	Session.on_new_call(my_py_func)

Given the registration above, MacTelnet calls the specified Python function every time a session is created.  If you were to run MacTelnet with a console attached to standard output, you would see the print statements appear as new windows are opened.

Currently, the callback is not given arguments.

If you wish to unregister your callback, use Session.stop_new_call().

Triggering Callbacks to Handle URLs

The Session module has the on_urlopen_call() method for registering a handler for a particular schema (type) of URL.  The core MacTelnet URL handlers are in fact entirely implemented in Python, and are installed using calls like this:

	Session.on_urlopen_call(HandleURL.telnet, 'telnet')

Your Python routine receives a single string argument that is a URL.  You are expected to create a new Session that properly handles the URL.

For example, if you had the text-based web browser lynx installed, you might write code like this to automatically open web pages with it:

	def run_lynx_on_url( url ):
		session = Session(["/usr/local/bin/lynx", url])
	Session.on_urlopen_call(run_lynx_on_url, "http")

Since MacTelnet runs a Python interpreter, you can import standard Python libraries such as urlparse to help you implement your handler.

If you wish to unregister your callback, use Session.stop_urlopen_call().

Triggering Callbacks to Open Files

The Session module has the on_fileopen_call() method for registering a handler for a particular type of file.  The core MacTelnet file handlers are in fact entirely implemented in Python, and are installed using calls like this:

	Session.on_fileopen_call(HandleFile.script, extension='tcsh')

Keyword arguments identify which file attribute your handler is for (indicating the meaning of the string).  Currently, the only attribute available is file extension, excluding any dot; so in the example above, "tcsh" refers to any file ending in ".tcsh"; a matching pathname would be /Users/me/Scripts/runme.tcsh.

Your Python routine receives a single string argument that is a pathname.  You are expected to create a new Session that properly handles the file.

For example, suppose you want to open all Python files with the preferred text editor of the user:

	import os
	def open_with_user_editor( pathname ):
		editor = '/usr/bin/vim'
		if 'EDITOR' in os.environ: editor = os.environ['EDITOR']
		session = Session([editor, pathname])
	Session.on_fileopen_call(open_with_user_editor, "py")

Since MacTelnet runs a Python interpreter, you can import standard Python libraries such as os.path to help you implement your handler.

If you wish to unregister your callback, use Session.stop_fileopen_call().

Setting Environment Variables

Since the front-end script RunMacTelnet.py is in Python, you can use the standard Python os.environ mechanism to configure environment variables.  This tends to be used only for special purposes.

For example, Apple-provided features like MallocGuardEdges and MallocScribble can be enabled when debugging, influencing the memory allocator.  The following Python statement sets MallocGuardEdges to 1:

	os.environ['MallocGuardEdges'] = '1'

Embedded settings are used no matter how MacTelnet is run; for example, you could launch MacTelnet from the Finder, and your custom environment would still be in effect.