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:



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

def <<(child)
  children << child
end

#[](path) ⇒ Object

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

See Also:



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

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

#ascii_plist_annotation ⇒ Object 



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

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.



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

def build_files
  referrers.grep(PBXBuildFile)
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.



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

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.



405
406
407
408
409
410
411
412
413
 
# File 'lib/xcodeproj/project/object/group.rb', line 405

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.



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/xcodeproj/project/object/group.rb', line 331

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_basename) ⇒ PBXFileReference

Creates a file reference to a new bundle.

Parameters:

  • product_basename (#to_s) —

    The name of the bundle.

Returns:



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

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:



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(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:



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

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:



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

#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:



286
287
288
289
290
291
292
293
 
# File 'lib/xcodeproj/project/object/group.rb', line 286

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:



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

#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:



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

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.



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



430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/xcodeproj/project/object/group.rb', line 430

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.



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/xcodeproj/project/object/group.rb', line 368

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.



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

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