Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A model querying and transformation library.

README.md

Welcome!

FunnyQT is a model querying and transformation library. It currently supports the Java Graph Laboratory and the Eclipse Modeling Framework.

Current build status: Build Status

Table of Contents

  1. Documentation
  2. Getting FunnyQT
  3. Getting Support

Documentation

Check out the overview description, the generated API documentation, and the papers about FunnyQT.

FunnyQT Overview

The FunnyQT API is structured into the following sub-APIs realized in several namespaces.

The foundation is an extensive core API providing typical model management services such as creating, loading, and storing models, accessing, creating, and deleting model elements, and accessing model element properties. The core API is subdivided into two framework-specific namespaces (EMF or JGraLab) and one namespace providing functions working with either kind of model representation.

  • funnyqt.emf: The EMF-specific core API
  • funnyqt.tg: The TGraph-specific core API (JGraLab)
  • funnyqt.protocols: Core functions working with both kinds of models/model elements

The functional querying API builds upon the core API and provides features such as navigation inside models in terms of role names, quantified expressions, and regular path expressions. Like the core API, some framework-specific parts are outsourced into their own two querying namespaces.

  • funnyqt.query: Generic querying services such as quantified expressions, sorting functions, and generic regular path operators.
  • funnyqt.query.emf: EMF-specific regular path operators
  • funnyqt.query.tg: TGraph-specific regular path operators

FunnyQT's polymorphic function API provides constructs for defining functions dispatching on metamodel type.

  • funnyqt.polyfns: Polymorphic function API

The pattern-matching API provides constructs for defining patterns using node and edge symbols. When a pattern is called on some model, it returns a lazy sequence of all matches in the model.

  • funnyqt.pmatch: Pattern-matching in models

Based on the pattern-matching API, there's a in-place transformation API that allows to define rules consisting of a pattern and a sequence of actions. When a rule is invoked, it searches for a match in the model and applies its actions to it. Typical control structures such as as-long-as-possible application of a rule are provided as higher-order functions.

  • funnyqt.in-place: In-place transformations

FunnyQT provides two kinds of model transformation APIs. The extensional model transformation API builds upon GReTL's concepts of extensional semantics and is an operational transformation API, whereas the model2model API realizes a rule-based approach to model transformations.

  • funnyqt.extensional: Generic parts of the extensional model transformation API
  • funnyqt.extensional.emf: The EMF-specific parts of the extensional model transformation API
  • funnyqt.extensional.tg: The TGraph-specific parts of the extensional model transformation API
  • funnyqt.model2model: The rule-based model transformation API

The relational querying API allows for Prolog-like logical querying of models using the core.logic library.

  • funnyqt.relational: Generic relations
  • funnyqt.relational.emf: EMF-specific relations
  • funnyqt.relational.tg: TGraph-specific relations

Based on the relational querying API, there's a bidirectional transformation API. Such a transformation specifies correspondences between a left and a right model in terms of relations between elements in those models. Such a transformation can be used to generate a new right model from a given left model and vice versa. Additionally, it can be used to synchronize between two existing models in either direction.

Finally, there are some utility and helper APIs.

  • funnyqt.utils: Generic utility functions
  • funnyqt.visualization: Visualizing models using GraphViz
  • funnyqt.xmltg: Converting arbitrary XML documents to DOM-like TGraphs and back again

API Documentation

The FunnyQT API docs generated for the current release are here.

Publications

Getting FunnyQT

There are two ways of getting FunnyQT. When you want to use it for writing your own queries and transformations, you should get the latest release available with Leiningen. If you want to have the bleeding edge version from git, e.g., to validate that some bug has been fixed, see how to get the git version.

Getting a Release

If you don't intend to hack on FunnyQT itself but you just want to use it for writing queries and transformations, the easiest possibility is to use the latest FunnyQT release that's available via the Clojars Maven repository.

To create query/transformation project using FunnyQT, simply perform the following steps:

  1. Install the lein shell (or bat) script as explained on the Leiningen homepage.

  2. Create a new project.

    $ lein new my-funnyqt-transform
    Generating a project called my-funnyqt-transform based on the 'default' template.
    To see other templates (app, lein plugin, etc), try `lein help new`.
    
  3. Declare that your project depends on FunnyQT. Replace 0.13.0 below with whatever is the the current FunnyQT release.

    $ cd my-funnyqt-transform
    $ edit project.clj
    # add funnyqt in the project :dependencies
    (defproject my-funnyqt-transform "0.1.0-SNAPSHOT"
      :description "FIXME: write description"
      :url "http://example.com/FIXME"
      :license {:name "Eclipse Public License"
                :url "http://www.eclipse.org/legal/epl-v10.html"}
      :dependencies [[org.clojure/clojure "1.5.1"]
                     [funnyqt "0.13.0"]])
    
  4. Now start a REPL and start hacking. Leiningen will take care of fetching all dependencies such as Clojure and FunnyQT.

    $ lein repl
    nREPL server started on port 39869 on host 127.0.0.1
    REPL-y 0.3.0
    Clojure 1.5.1
        Docs: (doc function-name-here)
              (find-doc "part-of-name-here")
      Source: (source function-name-here)
     Javadoc: (javadoc java-object-or-class-here)
        Exit: Control+D or (exit) or (quit)
     Results: Stored in vars *1, *2, *3, an exception in *e
    user=> ;; Here you go!
    

Getting the Git Version

FunnyQT uses Leiningen for retrieving all its dependencies from various Maven repositories, building, publishing, and test automation.

Getting started is really simple:

  1. Install the lein shell (or bat) script as explained on the Leiningen homepage.

  2. Clone the FunnyQT git repository:

    $ git clone https://github.com/jgralab/funnyqt.git
    
  3. Just to be sure everything's fine, you might want to execute the test cases.

    $ cd funnyqt
    $ lein test
    
  4. You are ready to go. Start a REPL and start hacking.

    $ lein repl
    REPL started; server listening on localhost port 22815
    user=> (use 'funnyqt.tg)
    nil
    user=> (def g (load-graph "test/input/greqltestgraph.tg"))
    #<Graph c06de1c7-f4ec0906-21cfbc86-28c31aa1 (1175): RouteMap>>
    user=> (vseq g 'localities.City)
    (#<v6: localities.City> #<v7: localities.City> #<v8: localities.City>)
    

Getting Support

Contact the Author

FunnyQT is developed by Tassilo Horn (tsdh). If you want, you can get in touch with me via email, IRC, or G+.

IRC Channel

Join us on the official JGraLab IRC Channel (channel #jgralab on irc.freenode.net). If you don't have or don't want to install an IRC client, you can also chat directly in your browser.

Found a Bug?

Although that should be quite impossible and is surely an error on your side >:), if you found a bug or miss an important feature, file a bug report in the FunnyQT issue tracker.

License

Copyright (C) 2011-2014 Tassilo Horn horn@uni-koblenz.de & The JGraLab Team ist@uni-koblenz.de

Distributed under the General Public License, Version 3 with the following additional grant:

Additional permission under GNU GPL version 3 section 7

If you modify this Program, or any covered work, by linking or combining it
with Eclipse (or a modified version of that program or an Eclipse plugin),
containing parts covered by the terms of the Eclipse Public License (EPL),
the licensors of this Program grant you additional permission to convey the
resulting work.  Corresponding Source for a non-source form of such a
combination shall include the source code for the parts of JGraLab used as
well as that of the covered work.
Something went wrong with that request. Please try again.