Class: Xcodeproj::Project::Object::PBXGroup

Inherits:
AbstractObject show all
Defined in:
lib/xcodeproj/project/object/group.rb

Overview

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

Direct Known Subclasses

PBXVariantGroup, XCVersionGroup

Instance Attribute Summary

Attributes inherited from AbstractObject

#isa, #project, #uuid

Attributes collapse

Helpers collapse

AbstractObject Hooks collapse

Methods inherited from AbstractObject

#<=>, #==, #inspect, isa, #pretty_print, #remove_from_project, #sort_recursively, #to_hash

Instance Method Details

#<<(child) ⇒ ObjectList<AbstractObject>

Adds an object to the group.

Returns:



326
327
328
 
# File 'lib/xcodeproj/project/object/group.rb', line 326

def <<(child)
  children << child
end

#[](path) ⇒ Object

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

See Also:



272
273
274
 
# File 'lib/xcodeproj/project/object/group.rb', line 272

def [](path)
  find_subpath(path, false)
end

#children ⇒ ObjectList<PBXGroup, PBXFileReference>

Returns the objects contained by the group.

Returns:



16
 
# File 'lib/xcodeproj/project/object/group.rb', line 16

has_many :children, [PBXGroup, PBXFileReference, PBXReferenceProxy]

#clear ⇒ Object Also known as: remove_children_recursively

Removes children files and groups under this group.



278
279
280
 
# File 'lib/xcodeproj/project/object/group.rb', line 278

def clear
  children.objects.each(&:remove_from_project)
end

#comments ⇒ String

Note:

This is apparently no longer used by Xcode.

Returns Comments associated with this group.

Returns:

  • (String) —

    Comments associated with this group.



77
 
# File 'lib/xcodeproj/project/object/group.rb', line 77

attribute :comments, String

#display_name ⇒ String

Returns the name of the group taking into account the path or other factors if needed.

Returns:

  • (String) —

    the name of the group taking into account the path or other factors if needed.



377
378
379
380
381
382
383
384
385
 
# File 'lib/xcodeproj/project/object/group.rb', line 377

def display_name
  if name
    name
  elsif path
    File.basename(path)
  elsif self.equal?(project.main_group)
    'Main Group'
  end
end

#empty? ⇒ Bool

Returns Whether the group is empty.

Returns:

  • (Bool) —

    Whether the group is empty.



204
205
206
 
# File 'lib/xcodeproj/project/object/group.rb', line 204

def empty?
  children.count.zero?
end

#files ⇒ Array<PBXFileReference>

Returns the file references in the group children.

Returns:



151
152
153
 
# File 'lib/xcodeproj/project/object/group.rb', line 151

def files
  children.grep(PBXFileReference)
end

#find_file_by_path(path) ⇒ PBXFileReference

of the source tree) matches the give path.

Returns:



158
159
160
 
# File 'lib/xcodeproj/project/object/group.rb', line 158

def find_file_by_path(path)
  files.find { |ref| ref.path == path }
end

#find_subpath(path, should_create = false) ⇒ PBXGroup, Nil

Note:

The path is matched against the #display_name of the groups.

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.

Examples:

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

Parameters:

  • path (String) —

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

  • should_create (Boolean) (defaults to: false) —

    whether the path should be created.

Returns:

  • (PBXGroup) —

    the group if found.

  • (Nil) —

    if the path could not be found and should create is false.



303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/xcodeproj/project/object/group.rb', line 303

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 ⇒ Array<PBXGroup>

Returns the groups in the group children.

Returns:

  • (Array<PBXGroup>) —

    the groups in the group children.



164
165
166
167
 
# File 'lib/xcodeproj/project/object/group.rb', line 164

def groups
  # Don't grep / is_a? as this would include child classes.
  children.select { |obj| obj.class == PBXGroup }
end

#hierarchy_path ⇒ String

Returns A representation of the group hierarchy.

Returns:

  • (String) —

    A representation of the group hierarchy.



99
100
101
 
# File 'lib/xcodeproj/project/object/group.rb', line 99

def hierarchy_path
  GroupableHelper.hierarchy_path(self)
end

#indent_width ⇒ String

Returns The width of the indent.

Examples:

`2`

Returns:

  • (String) —

    The width of the indent.



57
 
# File 'lib/xcodeproj/project/object/group.rb', line 57

attribute :indent_width, String

#move(new_parent) ⇒ void

This method returns an undefined value.

Moves the group to a new parent.

Parameters:

  • new_parent (PBXGroup) —

    The new parent.



110
111
112
 
# File 'lib/xcodeproj/project/object/group.rb', line 110

def move(new_parent)
  GroupableHelper.move(self, new_parent)
end

#name ⇒ String

Note:

If path is specified this attribute is not present.

Returns the name of the group.

Returns:

  • (String) —

    the name of the group.



43
 
# File 'lib/xcodeproj/project/object/group.rb', line 43

attribute :name, String

#new_bundle(product_name) ⇒ PBXFileReference

Creates a file reference to a new bundle.

Parameters:

  • product_name (#to_s) —

    The name of the bundle.

Returns:



245
246
247
 
# File 'lib/xcodeproj/project/object/group.rb', line 245

def new_bundle(product_name)
  FileReferencesFactory.new_bundle(self, product_name)
end

#new_group(name, path = nil, source_tree = :group) ⇒ PBXGroup

Note:

@see new_reference

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

Parameters:

  • name (#to_s) —

    the name of the new group.

Returns:



258
259
260
261
262
263
264
265
 
# File 'lib/xcodeproj/project/object/group.rb', line 258

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(target_name, product_type) ⇒ PBXFileReference

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

Parameters:

  • product_name (#to_s) —

    The name of the static library.

Returns:



234
235
236
 
# File 'lib/xcodeproj/project/object/group.rb', line 234

def new_product_ref_for_target(target_name, product_type)
  FileReferencesFactory.new_product_ref_for_target(self, target_name, product_type)
end

#new_reference(path, source_tree = :group) ⇒ PBXFileReference, XCVersionGroup Also known as: new_file

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.

Parameters:

  • path (#to_s) —

    The, preferably absolute, path of the reference.

  • source_tree (Symbol) (defaults to: :group) —

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

Returns:



221
222
223
 
# File 'lib/xcodeproj/project/object/group.rb', line 221

def new_reference(path, source_tree = :group)
  FileReferencesFactory.new_reference(self, path, source_tree)
end

#parent ⇒ PBXGroup, PBXProject

Returns The parent of the group.

Returns:



86
87
88
 
# File 'lib/xcodeproj/project/object/group.rb', line 86

def parent
  GroupableHelper.parent(self)
end

#parents ⇒ Array<PBXGroup, PBXProject>

Returns The list of the parents of the group.

Returns:



93
94
95
 
# File 'lib/xcodeproj/project/object/group.rb', line 93

def parents
  GroupableHelper.parents(self)
end

#path ⇒ String

Note:

This attribute is present for groups that are linked to a folder in the file system.

Returns the path to a folder in the file system.

Returns:

  • (String) —

    the path to a folder in the file system.



37
 
# File 'lib/xcodeproj/project/object/group.rb', line 37

attribute :path, String

#real_path ⇒ Pathname

source tree.

Returns:

  • (Pathname) —

    the absolute path of the group resolving the



117
118
119
 
# File 'lib/xcodeproj/project/object/group.rb', line 117

def real_path
  GroupableHelper.real_path(self)
end

#recursive_children ⇒ Array<PBXGroup,PBXFileReference,PBXReferenceProxy>

Returns the recursive list of the children of the group.

Returns:



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/xcodeproj/project/object/group.rb', line 191

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 ⇒ Array<PBXGroup,PBXFileReference,PBXReferenceProxy>

Returns the recursive children of the group.

Returns:



179
180
181
182
183
184
185
186
 
# File 'lib/xcodeproj/project/object/group.rb', line 179

def recursive_children_groups
  result = []
  groups.each do |child|
    result << child
    result.concat(child.recursive_children_groups)
  end
  result
end

#set_path(path) ⇒ void

This method returns an undefined value.

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

Parameters:

  • the (#to_s) —

    path for the group.



138
139
140
141
142
143
144
145
146
 
# File 'lib/xcodeproj/project/object/group.rb', line 138

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) ⇒ void

This method returns an undefined value.

Sets the source tree of the group.

Parameters:

  • source_tree (Symbol, String) —

    The source tree, either a string or a symbol.



128
129
130
 
# File 'lib/xcodeproj/project/object/group.rb', line 128

def set_source_tree(source_tree)
  GroupableHelper.set_source_tree(self, source_tree)
end

#sort(options = nil) ⇒ void

This method returns an undefined value.

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

Parameters:

  • options (Hash) (defaults to: nil) —

    the sorting options.

Options Hash (options):

  • :groups_position (Symbol) —

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



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/xcodeproj/project/object/group.rb', line 398

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?
      File.extname(x.display_name.downcase) <=> File.extname(y.display_name.downcase)
    else
      result
    end
  end
end

#sort_by_type ⇒ void

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).

This method returns an undefined value.

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



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/xcodeproj/project/object/group.rb', line 340

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 ⇒ void

This method returns an undefined value.

Sorts the group by type recursively.



364
365
366
367
 
# File 'lib/xcodeproj/project/object/group.rb', line 364

def sort_recursively_by_type
  groups.each(&:sort_recursively_by_type)
  sort_by_type
end

#source_tree ⇒ String

Note:

The accepted values are:

  • ‘<absolute>` for absolute paths

  • ‘<group>` for paths relative to the group

  • ‘SOURCE_ROOT` for paths relative to the project

  • ‘DEVELOPER_DIR` for paths relative to the developer directory.

  • ‘BUILT_PRODUCTS_DIR` for paths relative to the build products directory.

  • ‘SDKROOT` for paths relative to the SDK directory.

Returns the directory to which the path is relative.

Returns:

  • (String) —

    the directory to which the path is relative.



30
 
# File 'lib/xcodeproj/project/object/group.rb', line 30

attribute :source_tree, String, '<group>'

#tab_width ⇒ String

Returns The width of the tabs.

Examples:

`2`

Returns:

  • (String) —

    The width of the tabs.



64
 
# File 'lib/xcodeproj/project/object/group.rb', line 64

attribute :tab_width, String

#uses_tabs ⇒ String

Returns Whether Xcode should use tabs for text alignment.

Examples:

`1`

Returns:

  • (String) —

    Whether Xcode should use tabs for text alignment.



50
 
# File 'lib/xcodeproj/project/object/group.rb', line 50

attribute :uses_tabs, String

#version_groups ⇒ Array<XCVersionGroup>

Returns the version groups in the group children.

Returns:

  • (Array<XCVersionGroup>) —

    the version groups in the group children.



172
173
174
 
# File 'lib/xcodeproj/project/object/group.rb', line 172

def version_groups
  children.grep(XCVersionGroup)
end

#wraps_lines ⇒ String

Returns Whether Xcode should wrap lines.

Examples:

`1`

Returns:

  • (String) —

    Whether Xcode should wrap lines.



71
 
# File 'lib/xcodeproj/project/object/group.rb', line 71

attribute :wraps_lines, String