class Xcodeproj::Project::Object::PBXGroup

This class represents a group. A group can contain other groups (PBXGroup) and file references (PBXFileReference).

Public Instance Methods

<<(child) click to toggle source

Adds an object to the group.

@return [ObjectList<AbstractObject>] the children list.

# File lib/xcodeproj/project/object/group.rb, line 355
def <<(child)
  children << child
end
[](path) click to toggle source

Traverses the children groups and finds the group with the given path, if exists.

@see find_subpath

# File lib/xcodeproj/project/object/group.rb, line 301
def [](path)
  find_subpath(path, false)
end
ascii_plist_annotation() click to toggle source
# File lib/xcodeproj/project/object/group.rb, line 416
def ascii_plist_annotation
  super unless self.equal?(project.main_group)
end
build_files() click to toggle source

@return [Array<PBXBuildFile>] the build files associated with the

current reference proxy.
# File lib/xcodeproj/project/object/group.rb, line 456
def build_files
  referrers.grep(PBXBuildFile)
end
clear() click to toggle source

Removes children files and groups under this group.

# File lib/xcodeproj/project/object/group.rb, line 307
def clear
  children.objects.each(&:remove_from_project)
end
Also aliased as: remove_children_recursively
display_name() click to toggle source

@return [String] the name of the group taking into account the path

or other factors if needed.
# File lib/xcodeproj/project/object/group.rb, line 406
def display_name
  if name
    name
  elsif path
    File.basename(path)
  elsif self.equal?(project.main_group)
    'Main Group'
  end
end
empty?() click to toggle source

@return [Bool] Whether the group is empty.

# File lib/xcodeproj/project/object/group.rb, line 205
def empty?
  children.count.zero?
end
files() click to toggle source

@return [Array<PBXFileReference>] the file references in the group

children.
# File lib/xcodeproj/project/object/group.rb, line 152
def files
  children.grep(PBXFileReference)
end
find_file_by_path(path) click to toggle source

@return [PBXFileReference] The file references whose path (regardless of the source tree) matches the give path.

# File lib/xcodeproj/project/object/group.rb, line 159
def find_file_by_path(path)
  files.find { |ref| ref.path == path }
end
find_subpath(path, should_create = false) click to toggle source

Traverses the children groups and finds the children with the given path, optionally, creating any needed group. If the given path is ‘nil` it returns itself.

@param [String] path

a string with the names of the groups separated by a '`/`'.

@param [Boolean] should_create

whether the path should be created.

@note The path is matched against the {#display_name} of the groups.

@example

g = main_group['Frameworks']
g.name #=> 'Frameworks'

@return [PBXGroup] the group if found. @return [Nil] if the path could not be found and should create is

false.
# File lib/xcodeproj/project/object/group.rb, line 332
def find_subpath(path, should_create = false)
  return self unless path
  path = path.split('/') unless path.is_a?(Array)
  child_name = path.shift
  child = children.find { |c| c.display_name == child_name }
  if child.nil?
    if should_create
      child = new_group(child_name)
    else
      return nil
    end
  end
  if path.empty?
    child
  else
    child.find_subpath(path, should_create)
  end
end
groups() click to toggle source

@return [Array<PBXGroup>] the groups in the group children.

# File lib/xcodeproj/project/object/group.rb, line 165
def groups
  # Don't grep / is_a? as this would include child classes.
  children.select { |obj| obj.class == PBXGroup }
end
hierarchy_path() click to toggle source

@return [String] A representation of the group hierarchy.

# File lib/xcodeproj/project/object/group.rb, line 100
def hierarchy_path
  GroupableHelper.hierarchy_path(self)
end
move(new_parent) click to toggle source

Moves the group to a new parent.

@param [PBXGroup] new_parent

The new parent.

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 111
def move(new_parent)
  GroupableHelper.move(self, new_parent)
end
new_bundle(product_basename) click to toggle source

Creates a file reference to a new bundle.

@param [#to_s] product_basename

The name of the bundle.

@return [PBXFileReference] The new file reference.

# File lib/xcodeproj/project/object/group.rb, line 246
def new_bundle(product_basename)
  FileReferencesFactory.new_bundle(self, product_basename)
end
new_file(path, source_tree = :group)
Alias for: new_reference
new_group(name, path = nil, source_tree = :group) click to toggle source

Creates a file reference to a new bundle and adds it to the group.

@note @see new_reference

@param [#to_s] name

the name of the new group.

@return [PBXGroup] the new group.

# File lib/xcodeproj/project/object/group.rb, line 259
def new_group(name, path = nil, source_tree = :group)
  group = project.new(PBXGroup)
  children << group
  group.name = name
  group.set_source_tree(source_tree)
  group.set_path(path)
  group
end
new_product_ref_for_target(product_basename, product_type) click to toggle source

Creates a file reference to a static library and adds it to the group.

@param [#to_s] product_basename

The name of the static library.

@return [PBXFileReference] The new file reference.

# File lib/xcodeproj/project/object/group.rb, line 235
def new_product_ref_for_target(product_basename, product_type)
  FileReferencesFactory.new_product_ref_for_target(self, product_basename, product_type)
end
new_reference(path, source_tree = :group) click to toggle source

Creates a new reference with the given path and adds it to the group. The reference is configured according to the extension of the path.

@param [#to_s] path

The, preferably absolute, path of the reference.

@param [Symbol] source_tree

The source tree key to use to configure the path (@see
GroupableHelper::SOURCE_TREES_BY_KEY).

@return [PBXFileReference, XCVersionGroup] The new reference.

# File lib/xcodeproj/project/object/group.rb, line 222
def new_reference(path, source_tree = :group)
  FileReferencesFactory.new_reference(self, path, source_tree)
end
Also aliased as: new_file
new_variant_group(name, path = nil, source_tree = :group) click to toggle source

Creates a new variant group and adds it to the group

@note @see new_group

@param [#to_s] name

the name of the new group.

@param [#to_s] path

The, preferably absolute, path of the variant group.
Pass the path of the folder containing all the .lproj bundles,
that contain files for the variant group.
Do not pass the path of a specific bundle (such as en.lproj)

@param [Symbol] source_tree

The source tree key to use to configure the path (@see
GroupableHelper::SOURCE_TREES_BY_KEY).

@return [PBXVariantGroup] the new variant group.

# File lib/xcodeproj/project/object/group.rb, line 287
def new_variant_group(name, path = nil, source_tree = :group)
  group = project.new(PBXVariantGroup)
  children << group
  group.name = name
  group.set_source_tree(source_tree)
  group.set_path(path)
  group
end
parent() click to toggle source

@return [PBXGroup, PBXProject] The parent of the group.

# File lib/xcodeproj/project/object/group.rb, line 87
def parent
  GroupableHelper.parent(self)
end
parents() click to toggle source

@return [Array<PBXGroup, PBXProject>] The list of the parents of the

group.
# File lib/xcodeproj/project/object/group.rb, line 94
def parents
  GroupableHelper.parents(self)
end
real_path() click to toggle source

@return [Pathname] the absolute path of the group resolving the source tree.

# File lib/xcodeproj/project/object/group.rb, line 118
def real_path
  GroupableHelper.real_path(self)
end
recursive_children() click to toggle source

@return [Array<PBXGroup,PBXFileReference,PBXReferenceProxy>] the

recursive list of the children of the group.
# File lib/xcodeproj/project/object/group.rb, line 192
def recursive_children
  result = []
  children.each do |child|
    result << child
    if child.is_a?(PBXGroup)
      result.concat(child.recursive_children)
    end
  end
  result
end
recursive_children_groups() click to toggle source

@return [Array<PBXGroup,PBXFileReference,PBXReferenceProxy>] the

recursive children of the group.
# File lib/xcodeproj/project/object/group.rb, line 180
def recursive_children_groups
  result = []
  groups.each do |child|
    result << child
    result.concat(child.recursive_children_groups)
  end
  result
end
remove_children_recursively()
Alias for: clear
remove_from_project() click to toggle source

In addition to removing the reference proxy, this will also remove any items related to this reference.

@see AbstractObject#remove_from_project

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 467
def remove_from_project
  build_files.each(&:remove_from_project)
  super
end
set_path(path) click to toggle source

Allows to set the path according to the source tree of the group.

@param [#to_s] the path for the group.

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 139
def set_path(path)
  if path
    source_tree
    GroupableHelper.set_path_with_source_tree(self, path, source_tree)
  else
    self.path = nil
    self.source_tree = '<group>'
  end
end
set_source_tree(source_tree) click to toggle source

Sets the source tree of the group.

@param [Symbol, String] source_tree

The source tree, either a string or a symbol.

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 129
def set_source_tree(source_tree)
  GroupableHelper.set_source_tree(self, source_tree)
end
sort(options = nil) click to toggle source

Sorts the to many attributes of the object according to the display name.

@param [Hash] options

the sorting options.

@option options [Symbol] :groups_position

the position of the groups can be either `:above` or
`:below`.

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 431
def sort(options = nil)
  children.sort! do |x, y|
    if options && groups_position = options[:groups_position]
      raise ArgumentError unless [:above, :below].include?(groups_position)
      if x.isa == 'PBXGroup' && !(y.isa == 'PBXGroup')
        next groups_position == :above ? -1 : 1
      elsif !(x.isa == 'PBXGroup') && y.isa == 'PBXGroup'
        next groups_position == :above ? 1 : -1
      end
    end

    result = File.basename(x.display_name.downcase, '.*') <=> File.basename(y.display_name.downcase, '.*')
    if result.zero?
      result = File.extname(x.display_name.downcase) <=> File.extname(y.display_name.downcase)
      if result.zero? && !(x.path.nil? || y.path.nil?)
        result = x.path.downcase <=> y.path.downcase
      end
    end
    result
  end
end
sort_by_type() click to toggle source

Sorts the children of the group by type and then by name.

@note This is safe to call in an object list because it modifies it

in C in Ruby MRI. In other Ruby implementation it can cause
issues if there is one call to the notification enabled
methods not compensated by the corespondent opposite (loss of
UUIDs and objects from the project).

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 369
def sort_by_type
  children.sort! do |x, y|
    if x.isa == 'PBXGroup' && !(y.isa == 'PBXGroup')
      -1
    elsif !(x.isa == 'PBXGroup') && y.isa == 'PBXGroup'
      1
    elsif x.display_name && y.display_name
      extname_x = File.extname(x.display_name)
      extname_y = File.extname(y.display_name)
      if extname_x != extname_y
        extname_x <=> extname_y
      else
        File.basename(x.display_name, '.*') <=> File.basename(y.display_name, '.*')
      end
    else
      0
    end
  end
end
sort_recursively_by_type() click to toggle source

Sorts the group by type recursively.

@return [void]

# File lib/xcodeproj/project/object/group.rb, line 393
def sort_recursively_by_type
  groups.each(&:sort_recursively_by_type)
  sort_by_type
end
version_groups() click to toggle source

@return [Array<XCVersionGroup>] the version groups in the group

children.
# File lib/xcodeproj/project/object/group.rb, line 173
def version_groups
  children.grep(XCVersionGroup)
end