<commit_before>**Build and manipulate tree structures in Ruby.**

*This library is currently being developed :)*

## Synopsis

Evergreen provides you with tree structures and related tools to perform manipulation and computation the easy way. Trees are a subset of graphs, which are used in a whole slew of computer science and mathematical problems: network modelization, datasets storage, scientific computation, load balancing, games and AI designs, … Trees are frequently used to mimic hierarchal structures such as filesystems, or modelize decisionnal patterns, for instance.

Evergreen is built upon [Graphy](http://github.com/bruce/graphy "Graphy on Github"), a ruby-powered Graph Theory library, and aims at being a fully-fledged, pithy solution for tree-like structures managment. See below for additionnal information about graphs, trees, arborescences, why they're different and how to make good use of them.

## A few words about *trees*

A Tree is a graph subject to three basic constraints: nodes are all connected, they must not form any loop, and the branches binding nodes have no preferential direction. A tree is not compelled to have a root node and leaves as you may think *prima facie*. Trees with such features are called arborescences and Evergreen has support for them, too.

Evergreen provides you with the following structures:

* RawTree: a tree-graph with only basic features
* **Tree**: a tree-graph with extended features built upon RawTree. That's what you'd want to use as a basic tree structure
* AVLTree (*not yet*)
* RedBlackTree (*not yet*)
* **Arborescence** (*not yet*): the structure everybody thinks of when asked about "trees", with a root, internal nodes and leaves

You can also extend those structures with hybrid behaviors (not Graph Theory compliant but may be useful):

* Directed (*not yet*): relax the *undirected* constraint
* Loopy (*not yet*): relax the *acyclic* constraint
* Atomic (*not yet*): relax the *connected* constraint

## Examples

To create an instance of a tree, you may use either:

inheritance/direct initialization:

    class MyTree < Evergreen::Tree; end
    tree = MyTree.new

    # or even simpler:
    tree = Evergreen::Tree.new

mixing-in a "builder" module:

    class MyTree
      include Evergreen::RawTreeBuilder
    end
    tree = MyTree.new

Actually the RawTree class is nothing but the mixin code snippet above.

`tree` is now a tree object shipping with some default options:

* it is a valid tree *per se* (undirected, acyclic, connected graph), and Evergreen API's methods will ensure it remains so
* no constraint for the branching number (number of branches per node)

What if we want to customize it a bit?

    # Not yet!
    tree = Evergreen::Tree.new do |conf|
      conf.branching_number = 4     # at most 4 children per node
      conf.unique = true            # no duplicated node names allowed
    end

## Install, first steps and bootstraping

In order to play with Evergreen, you must:

    git clone git://github.com/chikamichi/graphy.git
    cd graphy
    rake install

    cd..

    git clone git://github.com/chikamichi/evergreen.git
    cd evergreen
    rake install

Now you can play in IRB:

    $ irb
    ruby-1.9.1-p378 > require 'evergreen'
    => true 
    ruby-1.9.1-p378 > include Evergreen # so you won't have to prefix everything with "Evergreen::"
    => Object 
    ruby-1.9.1-p378 > t = Tree.new
    => #<Evergreen::Tree:0x000000020d5ac8 @vertex_dict={}, @vertex_labels={}, @edge_labels={}, @allow_loops=false, @parallel_edges=false, @edgelist_class=Set> 
    ruby-1.9.1-p378 > t.methods
    => # lot of stuff hopefully :)

A good way to get you started is by [reading the doc online](http://rdoc.info/projects/chikamichi/evergreen "Evergreen on rdoc.info"). You can locally generate the doc with any of the following commands (you'll need to have the `yard` gem installed):

    rake yard
    yardoc

Be sure to take a look at the tests in `spec/` as well, as they document the public API extensively.
<commit_msg>README update<commit_after>p=. !http://img547.imageshack.us/img547/2932/logoevergreen.png!
p=. **Build and manipulate tree structures in Ruby.**

## Synopsis

Evergreen provides you with tree structures and related tools to perform manipulation and computation the easy way. Trees are a subset of graphs, which are used in a whole slew of computer science and mathematical problems: network modelization, datasets storage, scientific computation, load balancing, games and AI designs, … Trees are frequently used to mimic hierarchal structures such as filesystems, or modelize decisionnal patterns, for instance.

Evergreen is built upon [Graphy](http://github.com/bruce/graphy "Graphy on Github"), a ruby-powered Graph Theory library, and aims at being a fully-fledged, pithy solution for tree-like structures managment. See below for additionnal information about graphs, trees, arborescences, why they're different and how to make good use of them.

## A few words about *trees*

A Tree is a graph subject to three basic constraints: nodes are all connected, they must not form any loop, and the branches binding nodes have no preferential direction. A tree is not compelled to have a root node and leaves as you may think *prima facie*. Trees with such features are called arborescences and Evergreen has support for them, too.

Evergreen (*currently under early development stage*) provides you with the following structures:

* RawTree: a tree-graph with only basic features
* **Tree**: a tree-graph with extended features built upon RawTree. That's what you'd want to use as a basic tree structure
* AVLTree (*not yet*)
* RedBlackTree (*not yet*)
* **Arborescence** (*not yet*): the structure everybody thinks of when asked about "trees", with a root, internal nodes and leaves

You can also extend those structures with hybrid behaviors (not Graph Theory compliant but may be useful):

* Directed (*not yet*): relax the *undirected* constraint
* Loopy (*not yet*): relax the *acyclic* constraint
* Atomic (*not yet*): relax the *connected* constraint

## Basic usage

To create an instance of a tree, you may use either inheritance or mixins.

### Inheritance or direct initialization

    class MyTree < Evergreen::Tree; end
    tree = MyTree.new

    # or even simpler:
    tree = Evergreen::Tree.new

### Mixing-in a "builder" module

    class MyTree
      include Evergreen::RawTreeBuilder
    end
    tree = MyTree.new

Actually the RawTree class is nothing but the mixin code snippet above.

### What you get

`tree` is now a Tree object, shipping with some default options:

* it is a valid tree *per se* (an undirected, acyclic, connected graph)
* Evergreen API's methods will ensure it remains so
* it has no constraint on its branching number (the number of branches per node)

## Install, first steps and bootstraping

In order to play with Evergreen, you must:

    # install a fork of Graphy
    git clone git://github.com/chikamichi/graphy.git
    cd graphy
    rake install

    cd..

    # install Evergreen
    git clone git://github.com/chikamichi/evergreen.git
    cd evergreen
    rake install

Now you can play in IRB:

    $ irb
    ruby-1.9.1-p378 > require 'evergreen'
    => true 
    ruby-1.9.1-p378 > include Evergreen # so you won't have to prefix everything with "Evergreen::"
    => Object 
    ruby-1.9.1-p378 > t = Tree.new
    => #<Evergreen::Tree:0x000000020d5ac8 @vertex_dict={}, @vertex_labels={}, @edge_labels={}, @allow_loops=false, @parallel_edges=false, @edgelist_class=Set> 
    ruby-1.9.1-p378 > t.methods
    => # lot of stuff hopefully :)

A good way to get you started is by [reading the doc online](http://rdoc.info/projects/chikamichi/evergreen "Evergreen on rdoc.info"). You can locally generate the doc with any of the following commands (you'll need to have the `yard` gem installed):

    rake yard
    yardoc

Be sure to take a look at the tests in `spec/` as well, as they document the public API extensively.

{'fraction_non_alphanumeric': 0.07733633183408296, 'fraction_numerical': 0.010494752623688156, 'mean_word_length': 3.956656346749226, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2158685', 'n_tokens_mistral': 2308, 'n_tokens_neox': 2151, 'n_words': 1063}