Сегодня я хотел бы поделиться опытом создания, а конкретно рассмотреть тему написания приложений, использующих Akonadi.

В качестве примера я рассмотрю простое консольное приложение, которое позволяет добавлять задачи в календарь. Почему консольное приложение? Во-первых, чтобы не отвлекаться на аспекты, не имеющие прямого отношения к Akonadi. Во-вторых, чтобы

Требования

Я использую Ubuntu 9.10 Karmic, в нем для работы необходимо наличие следующих пакетов:

• kdelibs5-dev - библиотеки KDE
• kdepimlibs5-dev - библиотеки PIM KDE
• libboost-dev - Boost

Соответственно:

sudo aptitude install kdelibs5-dev kdepimlibs5-dev libboost-dev

Каркас приложения

Итак, приступим к созданию такого приложения. Назовем его, например, addtodo. Для начала в директории будущего приложения создадим файлы для исходников:

CMakeLists.txt, файл для конфигурации и сборки:

PROJECT(add-todo)

find_package(KDE4 REQUIRED) # Находим модули KDE4
find_package(KdepimLibs REQUIRED) # Находим модули KDE PIM

include(KDE4Defaults)

add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS})
include_directories(${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${KDEPIMLIBS_INCLUDE_DIR} ${KDE4_INCLUDES})

set(CMAKE_CXX_FLAGS "-fexceptions")

kde4_add_executable(add-todo add_todo.cpp) # Добавляем цель

target_link_libraries(add-todo ${KDE4_PLASMA_LIBS} ${KDE4_KDEUI_LIBS} ${KDE4_AKONADI_LIBS} ${KDEPIMLIBS_KCAL_LIBS}) # Добавляем соответствующие библиотеки

add_todo_app.h, заголовочный файл:

#ifndef ADD_TODO_H
#define ADD_TODO_H

#include <QCoreApplication>

#include <KJob>

class AddTodo : public QCoreApplication {
    Q_OBJECT
public:
    AddTodo( int argc, char ** argv );
public slots:
    void collectionsFetched( KJob * job ); // Будет вызван, когда мы получим список коллекций
    void todoCreated( KJob * job ); // Будет вызван, когда мы создадим задачу
};

#endif // ADD_TODO_H

add_todo_app.cpp, здесь будет содержаться основной код:

#include "add_todo.h"

#include <QTextStream>

static QTextStream out( stdout ); // Поток для вывода данных

AddTodo::AddTodo( int argc, char ** argv ) : QCoreApplication( argc, argv ) {
    out << "Application started" << endl;
}

void AddTodo::collectionsFetched( KJob * job ) {
}

void AddTodo::todoCreated( KJob * job ) {
}

int main( int argc, char ** argv ) {
    AddTodo app( argc, argv ); // Создаем экземпляр приложения
    
    return app.exec(); // И входим в цикл обработки сигналов
}

Теперь можно проверить, что наше пока еще ничего не делающее приложение корректно собирается:

mkdir build
cd build
cmake ..
make

Если мы запустим приложение, то оно напишет "Application started" и уйдет в бесконечный цикл ожидания сигналов. Пускай, теперь будем добавлять полезную работу.

Получения списка коллекций через Akonadi

Для того, чтобы создать задачу через Akonadi, необходимо сначала получить ссылку на коллекцию (Akonadi::Collection), в которой мы будем ее создавать. Для этого мы получим все коллекции и выберем ту, которая поддерживает подходящий тип элементов. Получение коллекции в Akonadi осуществляется путем создания задачи Akonadi::CollectionFetchJob.

В начало add_todo.cpp добавим инклуды, импорт пространства имен Akonadi и объявим одну константу, в которой будет записан MIME-тип для задачи. Он необходим нам для того, чтобы выбрать подходящую задачу.

#include <QStringList>

#include <Akonadi/Collection>
#include <Akonadi/CollectionFetchJob>

using namespace Akonadi;

static QString todoMimeType( "text/calendar" ); // MIME-тип задачи

В конструктор приложения добавляем:

    CollectionFetchJob *job = new CollectionFetchJob( Collection::root(), CollectionFetchJob::FirstLevel, this ); // Создаем задачу
    
    connect( job, SIGNAL(result(KJob*)), this, SLOT(collectionsFetched(KJob*)) ); // Связываем сигнал и слот

В первой строке аргументы означают то, что мы получаем подколлекции корневой коллекции, причем только первого уровня.

В метод collectionsFetched добавляем код обработки и выбора нужной нам коллекции:

    out << "Collections fetched" << endl;
    
    if ( job->error() ) {
        out << "Error occurred: " << job->errorText() << endl;
        exit( -1 );
        return;
    }

    const CollectionFetchJob * fetchJob = qobject_cast<CollectionFetchJob*>( job ); // Приводим задачу к нужному типу
    
    const Collection * selectedCollection = 0; // Переменная для выбранной коллекции
    
    foreach( const Collection & collection, fetchJob->collections() ) {
        out << "Name: " << collection.name(); // Печатаем имя коллекции для отладки
        
        if ( collection.contentMimeTypes().contains( todoMimeType ) ) { // Проверяем, принимает ли коллекция нужный тип данных
            selectedCollection = &collection;
            break;
        }
    }
    
    if ( !selectedCollection ) { // Если не нашли подходящей коллекции, то печатаем ошибку и выходим
        out << "Error occurred: no valid collection found"<< endl;
        exit( -1 );
        return;
    }
    
    // А здесь будем создавать задачу

Создание задачи

Теперь у нас есть коллекция, в которую можно наконец добавить задачу. Для этого, необходимо сделать три вещи:

• Создать объект KCal::Todo, описывающий нашу задачу
• Создать объект Akonadi::Item, представляющий элемент данных в Akonadi
• Создать задачу создания нового элемента
• Обработать ее результат

Итак, приступим. Сначала подключим заголовочные файлы:

#include <Akonadi/Item>
#include <Akonadi/ItemCreateJob>

#include <kcal/todo.h>

#include <boost/shared_ptr.hpp>

Теперь напишем код для первых трех пунктов в конце метода collectionsFetched:

    KDateTime dueDate = KDateTime::fromString( arguments()[2], "%d.%m.%Y" ); // Парсим дату

    if ( !dueDate.isValid() ) { // Проверяем, что дата распарсилась
        out << "Error occured: invalid date '" << arguments()[2] << "'" << endl;
        exit( -2 );
    }

    KCal::Todo::Ptr todo( new KCal::Todo() );
    todo->setSummary( arguments()[1] ); // Текст
    todo->setDtDue( dueDate ); // Дата
    todo->setPercentComplete( 0 ); // Пока не выполнена
    todo->setHasStartDate( false ); // Начальная дата не установлена
    todo->setHasDueDate( true ); // Установлена дата выполнения

    Item item( todoMimeType );
    item.setPayload<KCal::Todo::Ptr>( todo );

    ItemCreateJob * itemCreateJob = new ItemCreateJob( item, *selectedCollection, this ); // Создаем задачу

    connect( itemCreateJob, SIGNAL(result(KJob*)), this, SLOT(todoCreated(KJob*)) ); // Связываем сигнал и слот

А в метод todoCreated добавим проверку:

    if ( job->error() ) {
        out << "Error occurred: " << job->errorText() << endl;
        exit( -1 );
        return;
    }

    out << "TODO created" << endl;
    quit();

Также, неплохо добавить в начало main проверку количества аргументов:

    if ( argc < 3 ) { // Проверяем количество аргументов
        out << "Usage: add-todo [text] [date]" << endl;
        return -2;
    }

Все, теперь программа завершена, можно скомпилировать ее и запустить следующим образом:

./add-todo "Something" 21.01.2010

После выполнения у вас в календаре должна появиться новая задача. Теперь можно что-то улучшать, например, добавить возможность распознавания ссылок на даты вида "today", "tomorrow", поддержку времени, категорий и много чего интересного...

Полный код можно посмотреть по ссылке.

Код примеров построен на основе плагина для Plasma Runner, который можно найти здесь и здесь.

• Создавать и уничтожать группы
• Присоединяться к группам и покидать их
• Получать оповещения о новых членах групп
• Отправлять сообщения конкретному процессу или всем процессам группы

Здесь я ограничусь начальной информацией и опишу создание простого группового чата на Java.

Начало работы

Итак, для начала надо скачать JGroups. Сделать это можно здесь: http://sourceforge.net/projects/javagroups/files/. При написании этой статьи я использовал версию 2.6.13.GA. Также, для работы требуется Apache Commons Logging, или что-то его заменяющее (например, jcl-over-slf4j). Скачать можно здесь: http://commons.apache.org/downloads/download_logging.cgi.

Если же Вы используете Maven, то можно добавить репозиторий JBoss:

  <repository>
    <id>jboss</id>
    <name>jboss</name>
    <url>http://repository.jboss.com/maven2</url>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>

  <dependency>
    <groupId>jgroups</groupId>
    <artifactId>jgroups</artifactId>
    <version>2.6.13.GA</version>
  </dependency>

  <dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.1.1</version>
  </dependency>

Возможно, необходимо настроить сетевой интерфейс для работы с мультикастом. В Linux, для этого необходимо добавить соответствующий роут:

route add -net 224.0.0.0 netmask 240.0.0.0 dev lo

Иницализация

Для того,чтобы создать канал необходимо создать объект класса JChannel, передав ему в конструктор параметры конфигурации. В примере в конфигурации я указываю адрес, который должен использоваться для канала. Полный список опций можно посмотреть в документации.

JChannel channel = new JChannel( "UDP(bind_addr=127.0.0.1)" );

channel.connect( "MyCluster" );

Отправка сообщений

Сообщения в JGroups представлены классом Message, который содержит адрес отправителя, адрес получателя и данные. Адреса представлены объектами класса Address, а данные - это любые сериализуемые объекты или просто массив байт. Например, чтобы создать сообщение для всей группой, содержащее строку можно написать:

new Message( null, null, "Some content" )

Чтобы отправить сообщение необходимо вызвать метод JChannel#send и передать ему сообщение в качестве параметра. Например:

channel.send( new Message( null, null, "Some content" ) )

Обработка сообщений

Теперь необходимо написать код, для обработки сообщений, приходящих приложению. Для этого необходимо вызвать метод JChannel#setReceiver, передав в качестве параметра объект, реализующий интерфейс Receiver. Например, чтобы просто выводить все полученные сообщения на печать достаточно написать следующий код:

channel.setReceiver( new ReceiverAdapter(){

	@Override
	public void receive( Message m ) {
		System.out.println( m.getObject() );
	}

} );

Простейший чат

Теперь можно собрать простейший чат. Он будет рассылать группе строки, принятые с консоли и печатать полученные строки на консоль. Пример код:

import java.io.BufferedReader;
import java.io.InputStreamReader;

import org.jgroups.JChannel;
import org.jgroups.Message;
import org.jgroups.ReceiverAdapter;

public class SimplestChat {

	public static void main( String[] args ) throws Exception {
		JChannel channel = new JChannel( "UDP(bind_addr=127.0.0.1)" );
		channel.setReceiver( new ReceiverAdapter() {

			@Override
			public void receive( Message m ) {
				System.out.println( m.getObject() );
			}

		} );
		channel.connect( "MyCluster" ); // Подключаемся к группе

		/**
		 * Цикл обработки команд с консоли
		 */
		BufferedReader in = new BufferedReader( new InputStreamReader( System.in ) );
		while ( true ) {

			String line = in.readLine();

			if ( line.equalsIgnoreCase( "quit" ) || line.equalsIgnoreCase( "exit" ) ) {
				break;
			}

			channel.send( new Message( null, null, line ) );
		}

		channel.close(); // Отключаемся от группы по завершению работы
	}

}

При запуске этот код должен выводить что-нибудь вроде:

  Nov 8, 2009 4:18:27 PM org.jgroups.JChannel init
  INFO: JGroups version: 2.6.13.GA

Что дальше?

Здесь я рассмотрел только создание канала и отправку сообщений группе. В стороне остались достаточно много моментов: адресация, сообщения конкретному процессу и, главное, управление группой. Желающие ознакомиться с ними могут заглянуть в документацию JGroups: http://jgroups.org/ug.html.

Я обнаружил то, что для такой, казалось бы, стандартной задачи в Rails нет полноценного готового решения, которое бы легко интегрировалось с существующим приложением. В связи с этим был написан свой.

Основными критериями при разработке были:

• Возможность быстрой интеграции в приложение.
• Хорошая расширяемость.
• Отсутствие чужого кода (в смысле кода плагина) в приложении, к чему часто приводит использование генераторов. В этом смысле я пытался равняться на Authlogic.

То, что получилось представляет из себя что-то среднее между генератором (что обеспечивает хорошую расширяемость и модифицируемость) и engine'ом (чтобы можно было легко обновлять его).

Установка и использование

Для работы плагина (в частности истории страниц) необходимо наличие гема diff-lcs. Для форматирования по умолчанию используется RedCloth, однако можно выбрать и другой форматтер. Таким образом:

gem install diff-lcs RedCloth

Для установки плагина достаточно выполнить в директории Rails-приложения:

script/plugin install git://github.com/alno/irwi

После установки необходимо сгенерировать миграцию, моделиь и контроллер... Стойте, это вовсе не значит, что у вас в приложении появится куча чужого кода, который непонятно как поддерживать! Контроллер и модель содержат всего по одной строке вида acts_as_* и генерируется для того, чтобы в последствии Вам было бы проще расширять функциональность. Вся собственная функциональность вики реализуется в файлах плагина, что позволяет безболезненно обновлять ее.

Итак, чтобы сгенерировать необходимые файлы необходимо вызвать соответсвующий генератор:

script/generate irwi_wiki

После вызова генератора в приложение будут произведены следующие изменения:

• Добавлен WikiPageController и соответствующий хелпер для обработки страниц
• Добавлены модели WikiPage и WikiPageVersion для представления страниц
• Будет сгенерирована миграция, создающая таблицы в БД

Также в роуты будет добавлена следующая строка:

  map.wiki_root '/wiki'

Как несложно догадаться, в ней указывается корень wiki в вашем приложении. Вы можете легко его изменить на тот, который Вам больше нравится.

Все, работающая вики в вашем приложении сгенерирована. В принципе, можно уже использовать ее, но наверное вам все-таки хотелось бы изменить некоторые ее аспекты под свое приложение, например, изменить шаблоны, используемые для отображения или привязать ее к своей системе пользователей и ограничить права на редактирование страниц. Об этом и пойдет речь далее.

Изменение внешнего вида

Изменение внешнего вида можно производить двумя путями:

• Замена шаблонов
• Замена стилей в дефолтных шаблонах

Для замены какого-то шаблона (включая partial'ы) необходимо определить шаблон с соответствующим именем в директории видов для вашего контроллера. Ничего необычного, правда? Если вы не знаете, что же туда писать, можете посмотреть на дефолтные шаблоны в исходниках плагина (они там в app/views), благо они крайне простые.

Скорее всего, вы будете применять первый способ, но о первом все же стоит упомянуть. По умолчанию в каждый дефолтный шаблон добавляется CSS с описанием дефолтного стиля. Наверное, вам захочется его выкинуть (и подключить свой собственный в layout'е). Для этого достаточно переопределить в хелпере метод wiki_page_style своим, который возвращает пустую строку. Таким образом вы просто уберете стили из страниц.

Привязка к пользователям

Что необходимо для того, чтобы привязать вики к существующей системе пользователей в приложении?

Самый простой случай, если модель вашего пользователя называется User и у вас в контроллере определен метод current_user, который возвращает текущего пользователя. Согласитесь, это достаточно распространенный случай. В этом случае вики автоматически привяжется к пользователям и считать текущего пользователя автором изменений.

Единственная проблема - на всех страницах имя пользователя будет отображаться как-нибудь вроде User123. Наверное, это все-таки не то, что вы хотите. Чтобы исправить эту ситуацию достаточно определить метод wiki_user в классе WikiPagesHelper. Например, следующим образом:

module WikiPagesHelper
  include Irwi::Helpers::WikiPagesHelper

  def wiki_user( user )
    user ? link_to( user.login, user_path( user ) ) : "Guest"
  end

end

Если же ваша модель называется как-то по-другому, придется добавить еще одну строчку при инициализации приложения:

Irwi.config.user_class_name = 'Account' # Разумеется, если ваша модель называется именно так

Я рекомендую для этого создать отдельный initializer, чтобы потом туда же добавлять и прочие опции, которые вы, быть может захотите установить, но в принципе, вы вольны поступать как вам хочется.

Ограничение прав на выполнение операций

Скорее всего, Вам захочется добавить ограничение прав на просмотр или редактирование страниц вики (вообще говоря, я считаю, что это весьма неплохая идея). Например, как минимум, дать права на редактирование только зарегистрированным пользователям.

Для этого необходимо всего-навсего переопределить в контроллере три метода, осуществляющие проверку прав: show_allowed?, history_allowed? и edit_allowed?. В каждом из методов необходимо проверить имеет ли текущий пользователь права на совершение действия (просмотр, просмотр истории, редактирование) с текущей страницей (@page) и соответственно вернуть что-то, что расценивается как исттина или как ложь. В случае, если соответствующий метод возвращает ложь, то действие не совершается и в контроллере вызывается метод not_allowed, который по умолчанию рендерит текст об ошибке, но скорее всего вам захочется переопределить и его (например, чтобы редиректить пользователя на страницу логина).

Таким образом, примерный код контроллера может выглядеть следующим образом:

class WikiPagesController < ApplicationController
  
  acts_as_wiki_pages_controller
  
  def show_allowed?
    true # Показывать всем
  end
  
  def history_allowed?
    true # И историю пусть все смотрят
  end
  
  def edit_allowed?
    current_user # А редактируют только те, кто залогинены
  end
  
  def not_allowed
    redirect_to login_path # Всех нарушителей редиректим на страницу логина
  end
  
end

Итого

Я вкратце описал использование своего плагина для вики в Rails. Некоторые моменты, конечно, остались за границами этой статьи, но я опишу их позже. Приветствуются всякие замечания, предложения и идеи (через комменты, github, или любые мои контакты), а также патчи и форки (если кто-то хочет добавить что-то в плагин).

В этой заметке я проведу небольшой обзор средств, используемых в настоящий момент для тестирования приложений на базе Ruby on Rails. Я не ставлю себе целью выбрать “лучшее” – я считаю, что этот выбор должен делать каждый сам, однако я попытаюсь показать различные варианты – чтобы было из чего выбирать.

Модульные и функциональные тесты

Здесь я рассмотрю основные средства, используемые для модульного и функционального тестирования в Rails-приложениях. Напомню, что модульные тесты используются для тестирования логики приложения, которая расположена в моделях, а также для тестирования различных независимых участков приложения, например, хелперов (helpers).

Test::Unit

Test::Unit является классическим средством тестирования в стиле xUnit. В Rails-приложениях именно он и используется по умолчанию. Набор тестов с его использованием описывается в виде класса, методы которого представляют различные тесты. В коде методов в необходимых точках добавляются проверки, представленные вызовами assert_*.

Ниже приведен пример простейшего теста с использованием Test::Unit:

require 'test/unit'

class MyTest < Test::Unit::TestCase
  # def setup
  # end

  # def teardown
  # end

  def test_fail
    assert(2 + 2 == 4, 'Assertion was false.')
  end
end

RDoc-документация для Test::Unit: http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html

RSpec

RSpec - средство, предназначенное для спецификации поведения кода. Я не хочу вдаваться в отличия спецификации от тестирования (и BDD от TDD), просто приведу пример спецификации модели с использованием RSpec:

describe "A new account" do

  before do
    @account = Account.new
  end

  it "should have a balance of $0" do
    @account.balance.should eql(Money.new(0, :dollars))
  end

end

Как видно из примера, RSpec представляет специальный язык в рамках Ruby для описания спецификаций. Следствием этого является то, что хорошо написанные спецификации легко читаются, практически как текст на английском языке.

Одним из минусов RSpec является то, что для проверки спецификаций требуются создавать специальные Rake-задачи в приложении, в отличии от тестов на основе Test::Unit, задачи для которого включены в Rails.

Сайт проекта: http://rspec.info

RDoc-документация для RSpec: http://rspec.rubyforge.org/rspec/1.2.8/

Test/Spec

Test/Spec предназначен для описания спецификаций, аналогичных RSpec на базе Test::Unit, что позволяет использовать те же самые стандартные задачи, что и для Test::Unit, а также совмещать тесты и спецификации.

require 'test/spec'

describe "Foo" do
  it "should bar" do
    (2 + 3).should.equal 5
  end
end

Сайт проекта Test/Spec и RDoc-документация: http://test-spec.rubyforge.org/

Shoulda

Shoulda - это средство, которое работает на базе Test::Unit и предоставляет некоторые дополнительные возможности, в частности специальный язык для описания конструкций в тестах и набор макросов для часто используемых проверок:

class UserTest < Test::Unit::TestCase

  should_have_many :posts

  should_not_allow_values_for :email, "blah", "b lah" 
  should_allow_values_for :email, "a@b.com", "asdf@asdf.com" 
  should_ensure_length_in_range :email, 1..100
  should_ensure_value_in_range :age, 1..100
  should_protect_attributes :password

  context "A User instance" do
    setup do
      @user = User.find(:first)
    end

    should "return its full name" do
      assert_equal 'John Doe', @user.full_name
    end

    context "with a profile" do
      setup do
        @user.profile = Profile.find(:first)
      end

      should "return true when sent #has_profile?" do
        assert @user.has_profile?
      end
    end
  end
end

Update: В настоящий момент Shoulda может быть использована и вместе с RSpec

Сайт проекта: http://www.thoughtbot.com/projects/shoulda/

Remarkable

Shoulda показала удобство использования макросов для распространенных задач в тестировании, однако она работала только над Test::Unit. Remarkable - это реализация набора макросов, аналогичных Shoulda для RSpec. Его использование позволяет описывать следующие спецификации:

describe Post do
  it { should belong_to(:user) }
  it { should have_many(:comments) }
  it { should have_and_belong_to_many(:tags) }

  it { should validate_presence_of(:body) }
  it { should validate_presence_of(:title) }
  it { should validate_uniqueness_of(:title, :allow_blank => true) }
end

Сайт проекта Remarkable и RDoc-документация: http://remarkable.rubyforge.org/

Блог проекта: http://www.nomedojogo.com/category/remarkable/

Исходный код Remarkable: http://github.com/carlosbrando/remarkable/tree/master

Интеграционные тесты - Cucumber

Cucumber, используемый для интеграционного тестирования приложений продолжает движение в сторону читабельности тестов - тестовые сценарии описываются буквально на естественном языке:

  Scenario: Add two numbers
    Given I have entered 13 into the calculator
    And I have entered 22 into the calculator
    When I press "+"
    Then the result should be 35 on the screen

И не только на английском:

  Сценарий: Сложение двух целых чисел
    Допустим я ввожу число 50
    И затем ввожу число 70
    Если я нажимаю "+"
    То результатом должно быть число 120

Написание сценариев в таком виде делает Cucumber просто незаменимым инструментом для тестирования Rails-приложений. Разумеется, некоторое количество кода писать все-таки приходится, для того чтобы описать что означают те или иные приложения.

Заключение

Здесь я описал некоторые средства, используемые для тестирования Rails-приложений. Я сознательно не затрагивал здесь различные библиотеки для создания mock-объектов или замены fixtures, возможно, в дальнейшем им можно посвятить отдельную заметку.

Поскольку я пишу и о C++, и о Java, и о Ruby, естественным было бы добавить туда уточнения вида “C++”, “Java” и “Ruby”, позволяющие включать в результаты поиска только страницы с заданными тэгами. Как это выглядит можно посмотреть на картинке внизу, или по после нажатия кнопки “Найти” в блоге справа вверху.

Здесь я опишу, как такое можно осуществить.

Настройка системы поиска

Для начала, разумеется, необходимо создать систему пользовательского поиска. Это можно сделать на странице Custom Search Engine. При создании системы в список сайтов необходимо, разумеется включить свой сайт (или сайты).

Затем, в настройках системы зайти в раздел Уточнения(Refinements). Там можно добавить уточнение, возникает форма вида (например, сначала добавим раздел Ruby):

Основная проблема состоит в том, что написать в строке слов, чтобы выбрать все страницы, содержащие тэг Ruby.

Пришлось поискать описание различных операторов расширенного поиска для Google. Наиболее подробное описание различных операторов поиска я нашел здесь. Однако, для решения задачи мне понадобились всего три:

• | - альтернативные варианты (или).
• [ и ] - скобки для группировки элементов в запросах.
• * - оператор, который обозначает одно произвольное слово. Например в запросе "Мама * раму" вместо * может находится ровно одно слово, то есть по этому запросу найдется текст "мама мыла раму", но не "мама мыла большую раму" или "мама раму".

Далее, в начале каждой записи после заголовка я вставил код, выводящий список всех тэгов записи, перед которым находилось слово "тэги". После этого пришлось подождать некоторое время, пока Google переиндексирует все страницы сайта =).

После того, как все страницы переиндексированы, можно легко выделить все, у которых первым тэгом является Ruby с помощью запроса "Тэги: Ruby"

Теперь необходимо учесть то, что тэг Ruby стоит не всегда на первом месте. Здесь-то и нужен оператор * - запрос для тэга на втором месте выглядит как "Тэги: * Ruby". Аналогично для третьего, четвертого и далее.

Чтобы сделать запрос, который выбирает все страницы, содержащие тэг на любом из первых N мест можно задать следующую конструкцию: ["Тэги: Ruby"|"Тэги: * Ruby"|"Тэги: * * Ruby"|"Тэги: * * * Ruby"|"Тэги: * * * Ruby"]. Тут N=5. Если Вы ставите больше тэгов, то запрос придется сделать несколько длинее.

Полученную строку запроса необходимо записать в "слова, добавляемые в поисковый запрос", а затем нажать "Сохранить". Повторив описанную процедуру для необходимых тэгов на страницу поиска можно получить следующую строку навигации:

Форма поиска

Для поиска Google предлагает AJAX-форму, однако мне больше понравился вариант стандартной формы:

<form action="http://www.google.com/cse" id="cse-search-box">
<input name="cx" value="012005588861949235995:unlj7xfsgyy" type="hidden">
<input name="ie" value="UTF-8" type="hidden">
<input name="q" size="30" type="text">
<input name="sa" value="Найти" type="submit">
</form>

012005588861949235995:unlj7xfsgyy - это идентификатор моей системы поиска. Соответственно, для Вашей системы он будет другой, найти его можно, например, в URL при редактировании системы поиска.

И поэтому я был очень рад обнаружить замечательный проект: Typus. Это плагин для Rails, позволяющий значительно упростить процесс создания админки для приложений.

Из его особенностей:

• Позволяет практически мгновенно создать простейшую админку для моделей (создание, удаление, редактирование).
• Автоматически поддерживаются связи между моделями.
• Админка является расширяемой.
• Не генерирует огромного объема кода, который потом никогда не расширяется. Только то, что необходимо – конфиграционный файл и классы констроллеров для расширения. Только классы, без кода системы администрирования в них!
• Поддерживается локализация админки (пнглийский, испанский, португальский и русский).
• Поддерживается экспорт данных в различные форматы.

Установка

Typus может быть установлен двумя способами:

1. Как обычный плагин Rails, для этого в директории приложения необходимо вызвать:
   

   $ script/plugin install git://github.com/fesplugas/typus.git

2. Через Ruby Gems, для этого в config/environment.rb необходимо добавить строку:
   

   config.gem 'typus'

После установки необходимо в директории приложения вызвать команды:

$ script/generate typus
$ rake db:migrate

В результате будут сгенерированы файлы конфигурации админки, контроллеры админки для всех существующих моделей и пара миграций, обеспечивающих работу системы пользователей Typus.

Также, для работы админки необходимо убедиться, что в конце файла config/routes.rb присутствуют строки:

map.connect ':controller.:format'
map.connect ':controller/:action/:id.:format'

Конфигурация

После установки плагина создается несколько файлов, хранящих конфигурацию:

1. config/initalizers/typus.rb – здесь хранятся общие настройки админки
2. config/typus/*.yml – здесь хранятся настройки для различных моделей
3. config/typus/*_roles.yml – здесь хранятся права доступа к моделям

В первом файле задаются имя приложения, используемая локаль и т.п. Вот часть опций из него:

Typus::Configuration.options[:app_name]
Typus::Configuration.options[:config_folder]
Typus::Configuration.options[:email]
Typus::Configuration.options[:locales]
Typus::Configuration.options[:recover_password]
Typus::Configuration.options[:root]
Typus::Configuration.options[:ssl]
Typus::Configuration.options[:templates_folder]
Typus::Configuration.options[:user_class_name]
Typus::Configuration.options[:user_fk]

Например, чтобы задать русскую локаль необходимо в соответствующей опции этого файла выставить:

Typus::Configuration.options[:locales] = [ [ "Русский", :ru ] ]

В файлах настроек для моделей хранится описание того, как модели должны отображаться в админке, в частности:

• Какие поля должны отображаться при каждом из действий;
• Какие связи должны редактироваться;
• По каким полям должна осуществляться фильтрация и поиск;
• В каком порядке должны выводится записи;
• И тому подобное…

Модификация админки

Сгенерированная админка может быть легко модифицирована одним из следующих способов:

• (банальный) Добавление новых контроллеров в админку;
• Добавление новых действий к существующим контроллерам. Действие описывается в сгенерированном контроллере, а его указание в конфигурационном файле админки позволяет привязать действие к интерфейсу администрирования;
• Переопределение видов;
• Добавление блоков в виды. В последнем случае нет необходимости переопределять весь интерфейс, достаточно толко создать партиалы, которые будут встроены в соответствующие участки интерфейса. Список возможных партиалов приведен ниже (где RESOURCE – имя редактируемой модели):
  

  views/admin/login/_{bottom|top}.html.erb
  views/admin/dashboard/_{bottom|sidebar|top}.html.erb
  views/admin/RESOURCE/_edit.html.erb
  views/admin/RESOURCE/_edit_{bottom|sidebar|top}.html.erb
  views/admin/RESOURCE/_index.html.erb
  views/admin/RESOURCE/_index_{bottom|sidebar|top}.html.erb
  views/admin/RESOURCE/_new.html.erb
  views/admin/RESOURCE/_new_{bottom|sidebar|top}.html.erb
  views/admin/RESOURCE/_show.html.erb
  views/admin/RESOURCE/_show_{bottom|sidebar|top}.html.erb
  

Пример приложения

На сайте проекта выложен специальный шаблон, позволяющий сгенерировать простое демонстрационное приложение. С его помощью, чтобы попробовать Typus достаточно выполнить в консоли:

$ rails example.com -m http://intraducibles.com/projects/typus/demo.txt
$ cd example.com && script/server

После этого можно заходить в админку по адресу http://127.0.0.1:3000/admin.

Обычное решение этой проблемы - умные указатели с подсчетом ссылок, обеспечивающие автоматическое освобождение памяти. Однако, достаточно часто встречаются случаи, когда их использование избыточно, например, когда объекты имеют всего одного владельца и подсчет ссылок, вообще говоря не нужен.

А судя по замерам, накладные расходы по производительности и памяти на подсчет ссылок достаточно велики: Boost smart pointer timings.

Что же делать в таких случаях? На помощь приходит очередная библиотека в составе Boost - Pointer Container Library. Она предоставляет основные контейнеры, схожие со стандартными, специально предназнченные для хранения указателей.

Использование

В примере мы будем использовать ptr_vector. Для него необходимо подключить один заголовочный файл:

#include <boost/ptr_container/ptr_vector.hpp>

Рассмотрим простейший пример использования, приведенный в документации библиотеки. Предположим, что у нас имеется классическая иерархия классов:

class animal
{
public:
    virtual      ~animal()   {}
    virtual void eat()       = 0;
    virtual int  age() const = 0;
    // ...
};

class mammal : public animal
{
    // ...
};

class bird : public animal
{
    // ...
};

Теперь, нам необходимо создать список животных. Для этого мы будем использовать контейнер ptr_vector:

boost::ptr_vector<animal> the_animals;

Сразу обращаем внимание: при объявлении контейнера * не указывается. Чтобы добавить объект в контейнер, вызываем метод push_back, аналогично стандартному контейнеру std::vector:

the_animals.push_back( new mammal("joe") );
the_animals.push_back( new bird("dodo") );

Теперь о доступе к элементам: контейнер предоставляет доступ к элементам не по указателям, а по ссылкам. То, есть необходимо писать следующим образом:

the_animals[0].eat(); // А в случае std::vector<animal*> это было бы vec[0]->eat();

boost::ptr_vector<animal>::iterator  i = vec.begin();
i->eat(); // Опять же, для std::vector это было бы (*i)->eat(); Не знаю как Вас, но меня такая запись всегда раздражала.

Еще одно отличие: обработка нулевых указателей. Стандартный vector позволяет добавлять элементы - нулевые указатели. ptr_vector - не позволяет (по умолчанию). То есть, следующий код вызывает исключение:

the_animals.insert( the_animals.begin(), 0 ); // Исключение

Однако, если Вам необходимо, Вы можете разрешить хранение нулевых указателей. Делается это следующим образом:

boost::ptr_vector< boost::nullable<animal> > the_animals_nullable;

the_animals_nullable.insert( the_animals_nullable.begin(), 0 ); // Это уже корректно

Клонирование и перемещение данных

Крайне важное отличие таких контейнеров от стандартных в том, что они не могут быть скопированы напрямую! В чем причина: предполагается, что каждый указатель в любой момент времени находится в одном из таких контейнеров, который и освободит память при необходимости. Если же скопировать содержимое, то Вы получили бы указатель в двух контейнерах, что привело бы к последующим проблемам с их удалением.

Однако, не все так плохо. Вместо копирования можно осуществлять другие операции:

• Во-первых, контейнеры можно клонировать, вызывая клонирование всех входящих в них элементов.
• Во-вторых, данные можно извлечь из контейнера. И затем, например, переместить в другой.

Сначала о клонировании. Для того, чтобы содержимео контейнера могло быть клонировано, для всех его элементов должны быть определены две функции:

namespace boost
{
    inline T* new_clone( const T& t )
    {
        // Здесь клонируем объект...
    }

    void delete_clone( const T* t )
    {
        // Здесь удаляем объект...
    }
}

Если Ваш компилятор поддерживает Argument-Dependent Lookup, то их можно объявлять не в пространстве имен boost, а в том, где расположен обрабатываемый ими тип.

После того, как такие функции объявлены, можно вызывать метод clone контейнера:

the_animal_clones = the_animals.clone();

Теперь об извлечении и перемещении. Контейнеры предоставляют набор методов, позволяющих извлечь указатель по итератору и переместить набор элементов в другой контейнер:

boost::ptr_vector<animal>::auto_type the_animal = the_animals.release( the_animals.begin() ); // Извлекаем первый элемент
the_animal->eat();

При этом auto_type представляет из себя аналог std::auto_ptr.

Для перемещения существуют два вариант метода transfer

another_zoo.transfer( another_zoo.end(), // Добавляем последним элементом
                      zoo.begin(),       // Первый элемент
                      zoo );             // Из этого контейнера

another_zoo.transfer( another_zoo.begin(), // Добавляем в конец
                      zoo.begin(),       // От первого
                      zoo.end(),         // До последнего
                      zoo );             // Из этого контейнера

Алгоритмы

К сожалению, с этими контейнерами нельзя использовать стандартные алгоритмы STL. Однако, некоторые основные реализованы в виде методов:

boost::ptr_vector<animal> zoo;
...
zoo.sort();                               // Предполагаем, что описан 'bool operator<( const animal&, const animal& )'
zoo.sort( std::less<animal>() );          // То же самое, обращаем внимание на отсутствие *
zoo.sort( zoo.begin(), zoo.begin() + 5 ); // Сортируем участок

zoo.unique();                             // Предполагаем, что описан 'bool operator==( const animal&, const animal& )'
zoo.unique( zoo.begin(), zoo.begin() + 5, my_comparison_predicate() ); 

zoo.erase_if( my_predicate() );

Однако, на самом деле, не все так плохо!

В стандартной библиотеке Ruby существует замечательная поддержка XML-RPC, о которой я немного расскажу далее.

Для создания простейшего клиента необходимо всего лишь подключить файл xmlrpc/client, создать объект клиента и вызывать функции RPC, как методы этого объекта. А возвращаемым значением метода является хэш выходных параметров.

  require 'xmlrpc/client'
  require 'pp'

  client = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php")
  result = client.call("sample.sumAndDifference", 5, 3)
  pp result

Это пример с сайта официальной документации. По идее, result должен представлять из себя хэш, в котором будут содержаться возвращаемые значения. Однако, этот пример не работает (как минимум у меня). При вызове он выдает исключение:

/usr/lib/ruby/1.8/xmlrpc/client.rb:555:in `do_rpc': Wrong content-type (received 'text/html' but expected 'text/xml'):  (RuntimeError)

Что же не так? Сервер, к которому обращается клиент почему-то возвращает в заголовке Content-Type значение text/html, хотя ожидается text/xml. Вообще говоря, это стоит считать багом настройки сервера, но если Вы осуществляете запросы к каким-то внешним сервисам, есть вероятность, что какой-то из них так же будет отсылать некорректный Content-Type.

Первое что мне пришло в голову - это отключить проверку в клиенте. Самый простой способ не требует никакой модификации кода библиотеки. Для этого перед использованием клиента необходимо поместить следующий код:

  XMLRPC::Client.class_eval do
    def parse_content_type(a)
      ['text/xml']
    end
  end

То есть мы просто подменяем метод parse_content_type с тем, чтобы он всегда возвращал text/xml. Теперь можно спокойно делать запросы к различным сервисам и вышеприведенный пример выведет что-то вроде:

{"sum"=>8, "difference"=>2}

Теперь можно использовать библиотеку для работы сразличными XML-RPC сервисами в сети.

Ссылки

• Ruby XMLRPC Documentation (En)

Подсветка будет осуществляться с помощью CodeRay, о котором я уже писал в прошлой заметке.

Итак, создание простейшего расширения для Radiant CMS:

Создание скелета расширения

Для того, чтобы создать скелет расширения необходимо вызвать скрипт script/generate extension в директории приложения. Например, для создания расширения с именем code:

script/generate extension code

# Uncomment this if you reference any of your controllers in activate
# require_dependency 'application'

class CodeExtension < Radiant::Extension
  version "1.0"
  description "Describe your extension here"
  url "http://yourwebsite.com/code"
  
  # define_routes do |map|
  #   map.namespace :admin, :member => { :remove => :get } do |admin|
  #     admin.resources :code
  #   end
  # end
  
  def activate
    # admin.tabs.add "Code", "/admin/code", :after => "Layouts", :visibility => [:all]
  end
  
  def deactivate
    # admin.tabs.remove "Code"
  end
  
end

Простейшее расширение

В расширение мы добавим один тэг <r:code>, который позволяет подсветить код с использованием библиотеки CodeRay. Для этого необходимо создать новый модуль, содержащий тэг. Например, code_tags.rb в директории lib расширения. Чтобы в модуле можно было объявлять тэги, в него необходимо включить Radiant::Taggable:

module CodeTags
  include Radiant::Taggable
end

module CodeTags
  include Radiant::Taggable

  desc %{
    Some tag description here...
  }
  tag 'code' do |tag|
    tag.expand
  end

end

Теперь, чтобы подкчлють модуль с тэгами в файле code_extension.rb в метод activate необходимо добавить подключение нашего модуля к классу Page:

Page.send :include, CodeTags

Таким образом, мы создали тэг r:code, который ничего не делает. Точнее, он просто выводит свое содержимое: tag.extend возвращает содержимое тэга. Теперь вспомним, как использовался CodeRay для подсветки кода:

CodeRay.scan( text, lang ).div( :line_numbers => :table, :css => :style, :style => :cycnus )

  tag 'code' do |tag|
    CodeRay.scan( tag.expand, 'ruby' ).div( :line_numbers => :table, :css => :style, :style => :cycnus )
  end

require 'coderay'

  tag 'code' do |tag|
    CodeRay.scan( tag.expand, tag.attr['lang'] || 'ruby' ).div( :line_numbers => :table, :css => :style, :style => :cycnus )
  end

Простейшее расширение для подсветки кода в Radiant готово и его можно использовать в своем блоге. Более продвинутый вариант такого расширения можно найти у меня на GitHub. Я добавил в него поддержку различных библиотек для подсветки кода (в частности, тех, о которых писал в прошлый раз).

Ссылки

• Creating Radiant Extensions, Part 1 (En)
• Creating Radiant Extensions, Part 2 (En)
• Установка Radiant CMS (Ru)

Так что, сегодня я расскажу о трех различных Ruby-библиотеках, используемых для подсветки синтаксиса:

• Syntax
• UltraViolet
• CodeRay

Также, я провел замеры производительности, так что в конце вы можете найти сравнение библиотек по производительности.

Syntax

Страница проекта: http://syntax.rubyforge.org/
Поддерживаемые языки: Ruby, XML, YAML
Плюсы: Существует плагин для Rails и описание, как интегрировать его в Radiant.
Минусы: Малое количество поддерживаемых языков и отсутствие готовых тем.

Установка:

gem install syntax

Простейший пример использования:

require 'rubygems'
require 'syntax/convertors/html'

convertor = Syntax::Convertors::HTML.for_syntax “ruby”

html = convertor.convert( File.read( “program.rb” ) )
puts html

Окромя возможности подсветки кода, библиотека предоставляет возможность просто разобрать текст на лексемы, с тем чтобы производить потом какую-то обработку:

require 'syntax'

tokenizer = Syntax.load "ruby"
tokenizer.tokenize( File.read( "file.rb" ) ) do |token|
  puts "group(#{token.group}, #{token.instruction}) lexeme(#{token})"
end

P.S: Буквально перед публикацией нашел тему для библиотеки, осуществляющую подсветку как на GitHub.

UltraViolet

Страница проекта: http://ultraviolet.rubyforge.org/
Поддерживаемые языки: C, C++, Ruby, Bibtex, Latex, Diff, HTML, CSS и многие другие
Плюсы: Использует файлы синтаксиса TextMate для подсветки, что сразу дает большое количество поддерживаемых языков.
Минусы: Документация на сайте достаточно скудная. При попытке копирования кода со страницы он копируется вместе с номерами строк (если они сгенерированы). Тянет за собой достаточно много зависимостей и медленней всех работает.

Установка:

gem install ultraviolet

При установке у меня возникла одна проблема: Ultraviolet тянет за собой гем Oniguruma, который требует, чтобы в системе была установлена библиотека Oniguruma, причем вместе с заголовочными файлами. В Ubuntu ее можно установить из пакета:

sudo apt-get install libonig2 libonig-dev

Для остальных – неплохое руководство по установке приведено здесь.

Пример использования:

require 'rubygems'
require 'uv'

result = Uv.parse( text, "xhtml", "ruby", true, "amy")

Передаваемые в функцию параметры:

1. text – исходный код


2. “xhtml” – выходной синтаксис


3. “ruby” – входной язык


4. true – рендерить номера строк


5. “amy” – тема

CodeRay

Страница проекта: http://coderay.rubychan.de/
Поддерживаемые языки: Ruby, C, Delphi, HTML, RHTML (Rails), Nitro-XHTML, CSS, Diff, Java, JavaScript, JSON, YAML
Плюсы: Судя по моим замерам работает быстрее всех. Имеет достаточно большое число опций, позволяющих настроить вывод.
Минусы: Встроенные темы выглядят немного бедновато, особенно применительно к C и Java.

Установка:

gem install coderay

Пример использования:

require 'rubygems'
require 'coderay'

tokens = CodeRay.scan( text, :ruby )

print tokens.div( :line_numbers => :table, :css => :class, :style => :cycnus )

Методы преобразования (div,html,..) принимают хэш аргументов:

• :tab_width – ширина табуляции в проблеах. По умолчанию: 8


• :css – как включать стили: указывая класс или явный стиль (:class и :style). По умолчанию: :class)


• :wrap – обернуть результат в тэг :page, :div, :span или не оборачивать (nil)


• :line_numbers – как включать номера строк (:table, :inline, :list или nil)


• :line_number_start – с какого номера строки начинать


• :bold_every – выделять каждый n-й номер строки жирным. По умолчанию: 10

CodeRay, также как и Syntax может использоваться для анализа исходного текста, поскольку полученный объект Tokens представляет из себя по сути список лексем с заданными типами.

Сравнение производительности

Ниже приведены замеры производительности библиотек при обработке фргаментов кода на Ruby и Xml:

                          user     system      total        real
ruby ultraviolet:    10.270000   0.600000  10.870000 ( 11.584088)
ruby coderay:         0.710000   0.030000   0.740000 (  0.923616)
ruby syntax:          2.030000   0.130000   2.160000 (  2.830979)
xml ultraviolet:      3.280000   0.190000   3.470000 (  3.793856)
xml coderay:          0.540000   0.000000   0.540000 (  0.701140)
xml syntax:           0.660000   0.060000   0.720000 (  0.854120)

А также график:

Можно увидеть, что самым шустрым оказался CodeRay, а UltraViolet самым медленным. Однако, как мне кажется, некоторая тормознутость UltraViolet окупается наличием огромного количества поддерживаемых языков и готовых тем.

Ссылки

• Syntax (En)
• Ultraviolet (En)
• Coderay (En)
• Syntax Gem (En)
• Colorful Ruby code for your blog (En)