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, #nested_object_for_hash, #pretty_print, #sort_recursively, #to_ascii_plist, #to_hash

Instance Method Details

#<<(child) ⇒ ObjectList<AbstractObject>

Adds an object to the group.

Returns:



355
356
357
 
# File 'lib/xcodeproj/project/object/group.rb', line 355

def <<(child)
  children << child
end

#[](path) ⇒ Object

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

See Also:



301
302
303
 
# File 'lib/xcodeproj/project/object/group.rb', line 301

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

#ascii_plist_annotation ⇒ Object 



416
417
418
 
# File 'lib/xcodeproj/project/object/group.rb', line 416

def ascii_plist_annotation
  super unless self.equal?(project.main_group)
end

#build_files ⇒ Array<PBXBuildFile>

Returns the build files associated with the current reference proxy.

Returns:

  • (Array<PBXBuildFile>) —

    the build files associated with the current reference proxy.



456
457
458
 
# File 'lib/xcodeproj/project/object/group.rb', line 456

def build_files
  referrers.grep(PBXBuildFile)
end

#children ⇒ ObjectList<PBXGroup, PBXFileReference>

Returns the objects contained by the group.

Returns:



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

has_many :children, [PBXGroup, PBXFileReference, PBXReferenceProxy, PBXFileSystemSynchronizedRootGroup]

#clear ⇒ Object Also known as: remove_children_recursively

Removes children files and groups under this group.



307
308
309
 
# File 'lib/xcodeproj/project/object/group.rb', line 307

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.



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

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.



406
407
408
409
410
411
412
413
414
 
# 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? ⇒ Bool

Returns Whether the group is empty.

Returns:

  • (Bool) —

    Whether the group is empty.



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

def empty?
  children.count.zero?
end

#files ⇒ Array<PBXFileReference>

Returns the file references in the group children.

Returns:



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

def files
  children.grep(PBXFileReference)
end

#find_file_by_path(path) ⇒ PBXFileReference

of the source tree) matches the give path.

Returns:



159
160
161
 
# 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) ⇒ 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.



332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# 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 ⇒ Array<PBXGroup>

Returns the groups in the group children.

Returns:

  • (Array<PBXGroup>) —

    the groups in the group children.



165
166
167
168
 
# 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 ⇒ String

Returns A representation of the group hierarchy.

Returns:

  • (String) —

    A representation of the group hierarchy.



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

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.



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

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.



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

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.



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

attribute :name, String

#new_bundle(product_basename) ⇒ PBXFileReference

Creates a file reference to a new bundle.

Parameters:

  • product_basename (#to_s) —

    The name of the bundle.

Returns:



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

def new_bundle(product_basename)
  FileReferencesFactory.new_bundle(self, product_basename)
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:



259
260
261
262
263
264
265
266
 
# 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) ⇒ PBXFileReference

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

Parameters:

  • product_basename (#to_s) —

    The name of the static library.

Returns:



235
236
237
 
# 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) ⇒ 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:



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

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

#new_variant_group(name, path = nil, source_tree = :group) ⇒ PBXVariantGroup

Note:

@see new_group

Creates a new variant group and adds it to the group

Parameters:

  • name (#to_s) —

    the name of the new group.

  • path (#to_s) (defaults to: nil) —

    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)

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

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

Returns:



287
288
289
290
291
292
293
294
 
# 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 ⇒ PBXGroup, PBXProject

Returns The parent of the group.

Returns:



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

def parent
  GroupableHelper.parent(self)
end

#parents ⇒ Array<PBXGroup, PBXProject>

Returns The list of the parents of the group.

Returns:



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

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.



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

attribute :path, String

#real_path ⇒ Pathname

source tree.

Returns:

  • (Pathname) —

    the absolute path of the group resolving the



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

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:



192
193
194
195
196
197
198
199
200
201
 
# 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 ⇒ Array<PBXGroup,PBXFileReference,PBXReferenceProxy>

Returns the recursive children of the group.

Returns:



180
181
182
183
184
185
186
187
 
# 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_from_project ⇒ void

This method returns an undefined value.

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

See Also:



467
468
469
470
 
# File 'lib/xcodeproj/project/object/group.rb', line 467

def remove_from_project
  build_files.each(&:remove_from_project)
  super
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.



139
140
141
142
143
144
145
146
147
 
# 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) ⇒ 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.



129
130
131
 
# 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) ⇒ 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`.



431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
 
# 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 ⇒ 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.



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# 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 ⇒ void

This method returns an undefined value.

Sorts the group by type recursively.



393
394
395
396
 
# File 'lib/xcodeproj/project/object/group.rb', line 393

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.



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

attribute :source_tree, String, '<group>'

#tab_width ⇒ String

Returns The width of the tabs.

Examples:

`2`

Returns:

  • (String) —

    The width of the tabs.



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

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.



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

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.



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

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.



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

attribute :wraps_lines, String