// obsługa skryptów w pythonie

1) ./configure --with-python
2) skrypty muszą znajdować się w ~/.gg/scripts
3) /help python
4) przykładowy skrypt:

	# skrypt ignorujący zmiany stanu zawierające w opisie coś, co
	# przypomina tytuł empetrójek.
	#
	# 20021215 wojtekka

	import ekg
	import re
		
	regulka = re.compile("^[A-Z].* - [A-Z].*")

	def init():
		ekg.printf("generic", "Załadowano super hiper skrypciora!")
		return 1
		
	def deinit():
		ekg.printf("generic", "Ta-jest, kapitanie")
	
	def handle_status(uin, name, status, descr):
		if not descr:
			return 1
			
		if regulka.match(descr):
			return 2
		else:
			return 1

***

skrypty pythonowe w ekg mają być naprawdę proste w pisaniu, w przeciwieństwie
do skryptów perlowych w irssi, które ciężko z początku zrozumieć. jest kilka
funkcji, które będą wywoływane przez ekg w szczególnych przypadkach. jeśli
któraś funkcja zwróci wartość 0, zdarzenie zostanie ignorowane, jeśli
charakter zdarzenia na to pozwala (wiadomości, zmiany stanu itp.). jeśli
zwróci 1, zdarzenie zostanie normalnie obsłużone przez ekg. jeśli zdarzenie 
wiąże się z wyświetleniem jakiegoś tekstu, zwrócenie wartości 2 powoduje
ukrycie informacji o nim, ale zostanie ono obsłużone przez ekg. jeśli zdarzenie
zwróci krotkę/entkę/cokolwiek (ang. tuple) o takim samym wyglądzie jak
argumenty funkcji, informacje o zdarzeniu zostaną zmienione na podane.
na przykład:

	def handle_msg(uin, name, msgclass, text, time, secure):
		if string.find(text, ":(((") != -1:
			text = "(zbyt smutny tekst, ukryto)"
			return (uin, name, msgclass, text, time, secure)

		return 1

oto lista wywoływanych funkcji:

- init()

  gdy skrypt jest ładowany. jeśli ta funkcja zwróci 0, skrypt nie zostanie
  załadowany.

- deinit()

  gdy skrypt jest usuwany z pamięci.

- handle_msg(uin, name, msgclass, text, time, secure)

  gdy ekg otrzymuje wiadomość. uin - numer nadawcy, name - jego nazwa,
  msgclass - klasa wiadomości, text - treść, secure - czy mamy do czynienia
  z odszyfrowaną wiadomością. jeśli zwróci 0, wiadomość zostanie zignorowana.
  gdy zwróci 2, wiadomość nie zostanie wyświetlona na ekranie. jeśli zwróci
  krotkę/entkę/cokolwiek (ang. tuple) o takich samych argumentach jak funkcja,
  dane zostaną zmienione.

- handle_msg_own(rcpts, text)

  gdy użytkownik wysyła wiadomość. rcpts jest _tekstową_ reprezentacją
  odbiorcy, dokładnie taką jak podał użytkownik (pierwszy argument /msg,
  /chat, /query itd). jeśli zwróci 0, wiadomość nie zostanie wysłana.

- handle_status(uin, name, status, descr)

  gdy ktoś zmienia stan. nazwy parametrów powinny być zrozumiałe. jeśli
  zwróci 0, zmiana stanu zostanie zignorowana. jeśli zwróci 2, zmiana stanu
  nie będzie ignorowana, ale nie zostanie wyświetlona. jeśli zwróci krotkę
  o takich samych argumentach jak funkcja, dane zostaną zmienione.

- handle_status_own(status, descr)

  gdy klient zmienia stan. jeśli zwróci 0, stan nie zostanie zmieniony.

- handle_keypress(meta, key)

  gdy zostaje wciśnięty klawisz o kodzie key. jeśli wcześniejszym kodem
  był 27, meta jest równe 27. zwracane wartości pochodzą z funkcji getch()
  biblioteki ncurses, więc dla większości klawiszy funkcyjnych są zwracane
  odpowiednie kody. ich listę można znaleźć w plikach nagłówkowych ncurses
  w stałych z przedrostkiem KEY_

- handle_command_line(target, line)

  gdy wpisane zostanie linia w oknie ekg. target, jeśli nie puste,
  zawiera alias/uin użytkownika, z którym trwa rozmowa w aktualnym oknie.

- handle_redraw_header()

  gdy należy odświeżyć nagłówek okna.

- handle_redraw_statusbar()

  gdy należy odświeżyć pasek stanu.

później zostaną dodane funkcje dotyczące wszystkich zdarzeń związanych
z sesją gg, plus obsługa interfejsu użytkownika (informacja o wysłanej linii itp.)

***

skrypty umieszczone w katalogu ~/.gg/scripts/autorun będą ładowane
automagicznie przy starcie ekg.

***

przykłady użycia modułu ekg w skryptach:

   ekg.printf("generic", "Jestem skryptem w Pythonie!")
   ekg.command("msg 123 hej!")
   ekg.disconnect()
   ekg.config.uin = 12345
   ekg.config.password = "test123"
   ekg.connect()

później dojdą funkcje wywoływania podstawowych komend typu ,,msg'' itp.
obsługa okienek, themów, itd, itd.

$Id$