<commit_before>= Ancestry

Ancestry is a gem/plugin that allows the records of a Ruby on Rails ActiveRecord model to be organised as a tree structure (or hierarchy). It uses a single, intuitively formatted database column, using a variation on the materialised path pattern. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single SQL query. Additional features are STI support, scopes, depth caching, depth constraints, easy migration from older plugins/gems, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.

= Installation

To apply Ancestry to any ActiveRecord model, follow these simple steps:

1. Install
   - <b>Rails 2</b>
     - See 1-3-stable branch
   - <b>Rails 3</b>
     - Add to Gemfile: <b>gem 'ancestry'</b>
     - Install required gems: <b>bundle install</b>

2. Add ancestry column to your table
   - Create migration: <b>rails g migration add_ancestry_to_[table] ancestry:string</b>
   - Add index to migration: <b>add_index [table], :ancestry</b> (UP) / <b>remove_index [table], :ancestry</b> (DOWN)
   - Migrate your database: <b>rake db:migrate</b>

3. Add ancestry to your model
   - Add to app/models/[model].rb: <b>has_ancestry</b>

Your model is now a tree!

= Using acts_as_tree instead of has_ancestry

In version 1.2.0 the <b>acts_as_tree</b> method was <b>renamed to has_ancestry</b> in order to allow usage of both the acts_as_tree gem and the ancestry gem in a single application. To not break backwards compatibility, the has_ancestry method is aliased with acts_as_tree if ActiveRecord::Base does not respond to acts_as_tree. acts_as_tree will continue to be supported in the future as I personally prefer it.

= Organising records into a tree

You can use the parent attribute to organise your records into a tree. If you have the id of the record you want to use as a parent and don't want to fetch it, you can also use parent_id. Like any virtual model attributes, parent and parent_id can be set using parent= and parent_id= on a record or by including them in the hash passed to new, create, create!, update_attributes and update_attributes!. For example:

  TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')

You can also create children through the children relation on a node:

  node.children.create :name => 'Stinky'

= Navigating your tree

To navigate an Ancestry model, use the following methods on any instance / record:

  parent           Returns the parent of the record, nil for a root node
  parent_id        Returns the id of the parent of the record, nil for a root node
  root             Returns the root of the tree the record is in, self for a root node
  root_id          Returns the id of the root of the tree the record is in
  root?, is_root?  Returns true if the record is a root node, false otherwise
  ancestor_ids     Returns a list of ancestor ids, starting with the root id and ending with the parent id
  ancestors        Scopes the model on ancestors of the record
  path_ids         Returns a list the path ids, starting with the root id and ending with the node's own id
  path             Scopes model on path records of the record
  children         Scopes the model on children of the record
  child_ids        Returns a list of child ids
  has_children?    Returns true if the record has any children, false otherwise
  is_childless?    Returns true is the record has no childen, false otherwise
  siblings         Scopes the model on siblings of the record, the record itself is included
  sibling_ids      Returns a list of sibling ids<commit_msg>Fix typo: 'childen' => 'children'.<commit_after>= Ancestry

Ancestry is a gem/plugin that allows the records of a Ruby on Rails ActiveRecord model to be organised as a tree structure (or hierarchy). It uses a single, intuitively formatted database column, using a variation on the materialised path pattern. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single SQL query. Additional features are STI support, scopes, depth caching, depth constraints, easy migration from older plugins/gems, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.

= Installation

To apply Ancestry to any ActiveRecord model, follow these simple steps:

1. Install
   - <b>Rails 2</b>
     - See 1-3-stable branch
   - <b>Rails 3</b>
     - Add to Gemfile: <b>gem 'ancestry'</b>
     - Install required gems: <b>bundle install</b>

2. Add ancestry column to your table
   - Create migration: <b>rails g migration add_ancestry_to_[table] ancestry:string</b>
   - Add index to migration: <b>add_index [table], :ancestry</b> (UP) / <b>remove_index [table], :ancestry</b> (DOWN)
   - Migrate your database: <b>rake db:migrate</b>

3. Add ancestry to your model
   - Add to app/models/[model].rb: <b>has_ancestry</b>

Your model is now a tree!

= Using acts_as_tree instead of has_ancestry

In version 1.2.0 the <b>acts_as_tree</b> method was <b>renamed to has_ancestry</b> in order to allow usage of both the acts_as_tree gem and the ancestry gem in a single application. To not break backwards compatibility, the has_ancestry method is aliased with acts_as_tree if ActiveRecord::Base does not respond to acts_as_tree. acts_as_tree will continue to be supported in the future as I personally prefer it.

= Organising records into a tree

You can use the parent attribute to organise your records into a tree. If you have the id of the record you want to use as a parent and don't want to fetch it, you can also use parent_id. Like any virtual model attributes, parent and parent_id can be set using parent= and parent_id= on a record or by including them in the hash passed to new, create, create!, update_attributes and update_attributes!. For example:

  TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')

You can also create children through the children relation on a node:

  node.children.create :name => 'Stinky'

= Navigating your tree

To navigate an Ancestry model, use the following methods on any instance / record:

  parent           Returns the parent of the record, nil for a root node
  parent_id        Returns the id of the parent of the record, nil for a root node
  root             Returns the root of the tree the record is in, self for a root node
  root_id          Returns the id of the root of the tree the record is in
  root?, is_root?  Returns true if the record is a root node, false otherwise
  ancestor_ids     Returns a list of ancestor ids, starting with the root id and ending with the parent id
  ancestors        Scopes the model on ancestors of the record
  path_ids         Returns a list the path ids, starting with the root id and ending with the node's own id
  path             Scopes model on path records of the record
  children         Scopes the model on children of the record
  child_ids        Returns a list of child ids
  has_children?    Returns true if the record has any children, false otherwise
  is_childless?    Returns true is the record has no children, false otherwise
  siblings         Scopes the model on siblings of the record, the record itself is included
  sibling_ids      Returns a list of sibling ids
{'fraction_non_alphanumeric': 0.05528973950026582, 'fraction_numerical': 0.002658160552897395, 'mean_word_length': 3.6972534332084894, 'pattern_counts': {'":': 0, '<': 47, '<?xml version=': 0, '>': 56, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, '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': '4384590', 'n_tokens_mistral': 2059, 'n_tokens_neox': 1982, 'n_words': 1090}