CFPropertyList

https://www.rubydoc.info/gems/CFPropertyList
Admin
A Ruby library for parsing and generating Apple's Property List (plist) files, which are used to...
Tokens:25,087
Snippets:254
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Guessing CFType hierarchy

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList.guess

Examples of using the guess method to convert Ruby objects into CFType structures.

```ruby
x = { 'a' => ['b','c','d'] } cftypes = CFPropertyList.guess(x)
```

```ruby
cftypes = CFPropertyList.guess(x,:convert_unknown_to_string => true,:converter_method => :to_hash, :converter_with_opts => true)
```

--------------------------------

### CFPropertyList::List#initialize

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Ainitialize

Initializes a new CFPropertyList object. Accepts an optional hash of parameters to specify the source file, data string, or format.

```APIDOC
## initialize(opts = {})

### Description
Initializes a new CFPropertyList instance. All arguments are optional.

### Parameters
- **opts** (Hash) - Optional - Configuration options for the list.
  - **:file** (String) - Path to a file to parse.
  - **:format** (Constant) - Format of the property list (e.g., FORMAT_BINARY, FORMAT_XML). Defaults to FORMAT_AUTO.
  - **:data** (String) - A string containing the property list data to parse.
  - **:formatted** (Boolean) - Optional formatting flag.

### Returns
- **List** - A new instance of CFPropertyList::List.
```

--------------------------------

### CFPropertyList::CFDictionary#initialize

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary%3Ainitialize

Initializes a new instance of the CFDictionary class with an optional initial value.

```APIDOC
## initialize(value = {})

### Description
Creates a new CFDictionary type.

### Parameters
- **value** (Hash) - Optional - The initial value for the dictionary, defaults to an empty hash.
```

--------------------------------

### Initialize CFPropertyList::List

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Ainitialize

Initializes a new instance of the List class. It accepts optional keys for :file, :format, and :data to load content upon instantiation.

```ruby
def initialize(opts={})
  @filename = opts[:file]
  @format = opts[:format] || FORMAT_AUTO
  @data = opts[:data]
  @formatted = opts[:formatted]

  load(@filename) unless @filename.nil?
  load_str(@data) unless @data.nil?
end
```

--------------------------------

### load(opts = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ParserInterface

Loads a PList from the configured source.

```APIDOC
## load(opts = {})

### Description
Loads a PList. This method is intended to be implemented by subclasses to handle the parsing logic.

### Parameters
- **opts** (Hash) - Optional - Configuration options for the load operation.

### Returns
- **Object** - The loaded PList data.
```

--------------------------------

### load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/PlainParser

Reads and parses property list data from a file or a raw string.

```APIDOC
## load(opts)

### Description
Reads a property list from a file or data string and parses it into an object.

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - The filename of the file to load.
  - **:data** (String) - The raw data string to parse.

### Raises
- **CFFormatError** - Raised if the content is invalid or the file is not found.
```

--------------------------------

### CFPropertyList::PlainParser#load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/PlainParser%3Aload

Reads and parses a plain format XML file or data string.

```APIDOC
## CFPropertyList::PlainParser#load(opts)

### Description
Reads a plain format property list from a file or a provided data string.

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - Optional - The filename of the file to load.
  - **:data** (String) - Optional - The data to parse.

### Returns
- **Object** - The parsed property list object.

### Raises
- **CFFormatError** - Raised if the content is invalid or if there is content after the root object.
```

--------------------------------

### initialize(value = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary

Creates a new instance of the CFDictionary class with an optional initial hash of values.

```APIDOC
## initialize(value = {})

### Description
Creates a new CFDictionary type.

### Parameters
- **value** (Hash) - Optional - A hash of values to initialize the dictionary with.
```

--------------------------------

### Create a new LibXML text node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Anew_text

This method initializes a new LibXML::XML::Node object containing the specified text value.

```ruby
def new_text(val)
  LibXML::XML::Node.new_text(val)
end
```

--------------------------------

### Initialize CFDictionary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary%3Ainitialize

Creates a new CFDictionary object with an optional initial value.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 300

def initialize(value={})
  @value = value
end
```

--------------------------------

### to_binary(bplist)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFData

Converts the data to a binary format.

```APIDOC
## to_binary(bplist)

### Description
Converts the current data object to binary format using the provided bplist object.
```

--------------------------------

### Create a new XML node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Anew_node

Instantiates a new LibXML::XML::Node object using the provided name parameter.

```ruby
def new_node(name)
  LibXML::XML::Node.new(name)
end
```

--------------------------------

### CFPropertyList::ReXMLParser#load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ReXMLParser%3Aload

Parses an XML file or data string and returns the corresponding object structure.

```APIDOC
## Method: CFPropertyList::ReXMLParser#load(opts)

### Description
Reads and parses an XML file or raw XML data string.

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - Optional - The path to the XML file to load.
  - **:data** (String) - Optional - The raw XML data to parse.

### Returns
- **Object** - The parsed representation of the XML content.

### Exceptions
- **CFFormatError** - Raised if the provided XML is invalid.
```

--------------------------------

### Convert CFPropertyList to binary format

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary%3Ato_str

Serializes the root object into a binary string representation. This method initializes internal tracking tables and calculates object offsets required for the binary format.

```ruby
def to_str(opts={})
  @unique_table = {}
  @count_objects = 0
  @object_refs = 0

  @written_object_count = 0
  @object_table = []

  @offsets = []

  binary_str = "bplist00"

  @object_refs = count_object_refs(opts[:root])

  opts[:root].to_binary(self)

  next_offset = 8
  offsets = @object_table.map do |object|
    offset = next_offset
    next_offset += object.bytesize
    offset
  end
  binary_str << @object_table.join

  table_offset = next_offset
  offset_size = Binary.bytes_needed(table_offset)

  if offset_size < 8
    # Fast path: encode the entire offset array at once.
    binary_str << offsets.pack((%w(C n N N)[offset_size - 1]) + '*')
  else
    # Slow path: host may be little or big endian, must pack each offset
    # separately.
    offsets.each do |offset|
      binary_str << "#{Binary.pack_it_with_size(offset_size,offset)}"
    end
  end

  binary_str << [offset_size, object_ref_size(@object_refs)].pack("x6CC")
  binary_str << [@object_table.size].pack("x4N")
  binary_str << [0].pack("x4N")
  binary_str << [table_offset].pack("x4N")

  binary_str
end
```

--------------------------------

### CFPropertyList::CFData#initialize

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFData%3Ainitialize

Initializes a new CFData instance with an optional value and format. The format determines whether the provided value is treated as raw data or base64 encoded.

```APIDOC
## initialize(value = nil, format = DATA_BASE64)

### Description
Initializes a new CFData object. The method sets the internal value based on the provided format, which can be either raw data or base64 encoded.

### Parameters
- **value** (Object) - Optional - The data value to initialize the object with.
- **format** (Constant) - Optional - The format of the data, defaults to DATA_BASE64. Use DATA_RAW for raw data.

### Returns
- **CFData** - A new instance of the CFData class.
```

--------------------------------

### Load XML PropertyList

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_xml

Loads an XML PropertyList from the specified file or the instance's default filename.

```ruby
def load_xml(filename=nil)
  load(filename,List::FORMAT_XML)
end
```

--------------------------------

### CFPropertyList::ParserInterface#load

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ParserInterface%3Aload

Loads a plist configuration. This method is part of the ParserInterface and accepts an optional hash of parameters.

```APIDOC
## load(opts = {})

### Description
Loads a plist file or data structure.

### Parameters
- **opts** (Hash) - Optional - Configuration options for the loading process.

### Returns
- **Object** - The loaded plist data.
```

--------------------------------

### Initialize CFData

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFData

Constructor for setting the initial value and format of the data object.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 235

def initialize(value=nil,format=DATA_BASE64)
  if(format == DATA_RAW)
    @raw_value = value
  else
    @value = value
  end
end
```

--------------------------------

### Initialize CFData object

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFData%3Ainitialize

Sets the internal value based on the provided format, defaulting to DATA_BASE64.

```ruby
def initialize(value=nil,format=DATA_BASE64)
  if(format == DATA_RAW)
    @raw_value = value
  else
    @value = value
  end
end
```

--------------------------------

### CFPropertyList::CFDate#initialize

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDate%3Ainitialize

Initializes a new CFDate object. The method accepts an optional value and a format parameter to define the date state.

```APIDOC
## CFPropertyList::CFDate#initialize

### Description
Initializes a new instance of the CFDate class. It sets the internal value based on the provided input, which can be a Time, Date, or DateTime object, or a formatted value.

### Signature
`initialize(value = nil, format = CFDate::TIMESTAMP_UNIX) -> CFDate`

### Parameters
- **value** (Time, Date, DateTime, or Object) - Optional - The date value to initialize. Defaults to the current time if nil.
- **format** (Constant) - Optional - The format of the provided value, defaulting to CFDate::TIMESTAMP_UNIX.
```

--------------------------------

### Create New Text Node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/NokogiriXMLParser

Creates a new XML text node.

```ruby
# File 'lib/cfpropertylist/rbNokogiriParser.rb', line 64

def new_text(val)
  @doc.create_text_node val
end
```

--------------------------------

### initialize(val = [])

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFArray

Creates a new CFArray instance with an optional initial array of values.

```APIDOC
## initialize(val = [])

### Description
Creates a new CFArray instance. The optional `val` parameter accepts an array of values to initialize the object.

### Parameters
- **val** (Array) - Optional - An array of values to initialize the CFArray.
```

--------------------------------

### CFPropertyList::List#format

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aformat

Returns the original format of the PropertyList.

```APIDOC
## CFPropertyList::List#format

### Description
Returns the original format of the PropertyList object.

### Method
`format`

### Returns
- **Object** - The original format of the PropertyList.
```

--------------------------------

### Load a plain property list file

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_plain

Reads a plain plist file from the specified filename or the instance's default filename.

```ruby
# File 'lib/cfpropertylist/rbCFPropertyList.rb', line 265

def load_plain(filename=nil)
  load(filename,List::FORMAT_PLAIN)
end
```

--------------------------------

### CFPropertyList::List#load_plain_str

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_plain_str

Loads a plist from a plain string.

```APIDOC
## load_plain_str(str = nil)

### Description
Loads a property list from a plain string.

### Parameters
- **str** (String) - Optional - The string containing the plist data.
```

--------------------------------

### CFPropertyList::List#filename

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Afilename

Returns the path of the PropertyList.

```APIDOC
## filename

### Description
Returns the path of the PropertyList associated with the current instance.

### Signature
`filename ⇒ Object`

### Returns
- **Object** - The path of the PropertyList.
```

--------------------------------

### Serialize to binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFType

Interface method for binary serialization.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 40

def to_binary(bplist)
end
```

--------------------------------

### CFPropertyList::List#load_binary_str

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_binary_str

Loads a plist from a binary string.

```APIDOC
## load_binary_str(str = nil)

### Description
Loads a property list from a binary string.

### Parameters
- **str** (String) - Optional - The string containing the plist data.
```

--------------------------------

### Load a plist from a plain string

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_plain_str

This method loads a plist from a provided string using the FORMAT_PLAIN constant.

```ruby
def load_plain_str(str=nil)
  load_str(str,List::FORMAT_PLAIN)
end
```

--------------------------------

### to_binary(bplist)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFUid

Converts the UID value to binary format using the provided bplist object.

```APIDOC
## to_binary(bplist)

### Description
Converts the UID value to binary format.

### Parameters
- **bplist** (Object) - Required - The binary property list object used for conversion.
```

--------------------------------

### Define to_binary method

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFType%3Ato_binary

The method signature for to_binary as defined in the CFPropertyList library.

```ruby
def to_binary(bplist)
end
```

--------------------------------

### load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ReXMLParser

Reads and parses an XML file or raw XML data.

```APIDOC
## load(opts)

### Description
Reads an XML file or parses raw XML data provided in the options hash.

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - The filename of the file to load.
  - **:data** (String) - The raw XML data to parse.
```

--------------------------------

### Load a plist using ParserInterface

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ParserInterface%3Aload

The load method is a placeholder implementation that returns an empty string.

```ruby
# File 'lib/cfpropertylist/rbCFPropertyList.rb', line 53

def load(opts={})
  return ""
end
```

--------------------------------

### to_plain(plist)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary

Converts the dictionary instance to a plain text representation.

```APIDOC
## to_plain(plist)

### Description
Converts the dictionary to a plain text format.

### Parameters
- **plist** (Object) - Required - The property list object used for conversion.
```

--------------------------------

### Implementation of CFPropertyList.guess

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList.guess

The source code implementation of the guess method, defining how various Ruby classes are mapped to CFPropertyList types.

```ruby
def guess(object, options = {})
  case object
  when Integer               then CFInteger.new(object)
  when UidFixnum             then CFUid.new(object)
  when Float                 then CFReal.new(object)
  when TrueClass, FalseClass then CFBoolean.new(object)

  when Blob
    CFData.new(object, CFData::DATA_RAW)

  when String, Symbol
    CFString.new(object.to_s)

  when Time, DateTime, Date
    CFDate.new(object)

  when Array, Enumerator
    ary = Array.new
    object.each do |o|
      ary.push CFPropertyList.guess(o, options)
    end
    CFArray.new(ary)

  when Hash
    hsh = Hash.new
    object.each_pair do |k,v|
      k = k.to_s if k.is_a?(Symbol)
      hsh[k] = CFPropertyList.guess(v, options)
    end
    CFDictionary.new(hsh)
  else
    case
    when Object.const_defined?('BigDecimal') && object.is_a?(BigDecimal)
      CFReal.new(object)
    when object.respond_to?(:read)
      raw_data = object.read
      # treat the data as a bytestring (ASCII-8BIT) if Ruby supports it.  Do this by forcing
      # the encoding, on the assumption that the bytes were read correctly, and just tagged with
      # an inappropriate encoding, rather than transcoding.
      raw_data.force_encoding(Encoding::ASCII_8BIT) if raw_data.respond_to?(:force_encoding)
      CFData.new(raw_data, CFData::DATA_RAW)
    when options[:converter_method] && object.respond_to?(options[:converter_method])
      if options[:converter_with_opts]
        CFPropertyList.guess(object.send(options[:converter_method],options),options)
      else
        CFPropertyList.guess(object.send(options[:converter_method]),options)
      end
    when options[:convert_unknown_to_string]
      CFString.new(object.to_s)
    else
      raise CFTypeError.new("Unknown class #{object.class.to_s}. Try using :convert_unknown_to_string if you want to use unknown object types!")
    end
  end
end
```

--------------------------------

### Load a binary plist file

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_binary

Reads a binary property list file. If no filename is provided, it defaults to the instance variable filename.

```ruby
def load_binary(filename=nil)
  load(filename,List::FORMAT_BINARY)
end
```

--------------------------------

### CFPropertyList::List#load(file = nil, format = nil)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload

Reads a plist file from the filesystem. If no file is provided, it uses the instance's filename variable. If the format is not specified, it attempts to auto-detect the file format.

```APIDOC
## CFPropertyList::List#load

### Description
Reads a plist file from the specified path. If no file is provided, it defaults to the instance's filename. The format can be explicitly set or auto-detected.

### Signature
`load(file = nil, format = nil) -> Object`

### Parameters
- **file** (String) - Optional - The path to the plist file to read.
- **format** (Integer) - Optional - The format constant of the plist file. If nil, the format is auto-detected.

### Raises
- **IOError** - Raised if the file is not readable or is empty.
- **CFFormatError** - Raised if the file format is invalid or a parser error occurs.
```

--------------------------------

### Create new text node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ReXMLParser

Returns the provided value as a text node representation.

```ruby
# File 'lib/cfpropertylist/rbREXMLParser.rb', line 60

def new_text(val)
  val
end
```

--------------------------------

### Initialize CFArray

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFArray%3Ainitialize

Creates a new CFArray instance with an optional initial value, defaulting to an empty array.

```ruby
def initialize(val=[])
  @value = val
end
```

--------------------------------

### CFPropertyList::List#load_binary(filename = nil)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_binary

Reads a binary plist file. If no filename is provided, it defaults to the file defined by the instance variable.

```APIDOC
## CFPropertyList::List#load_binary

### Description
Reads a binary plist file into the current object.

### Method
Ruby Method

### Signature
load_binary(filename = nil) -> Object

### Parameters
- **filename** (String) - Optional - The path to the binary plist file. If nil, the method uses the filename stored in the instance variable.
```

--------------------------------

### CFPropertyList::LibXMLParser#new_node(name)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Anew_node

Creates a new XML node using the LibXML parser interface.

```APIDOC
## new_node(name)

### Description
Creates and returns a new LibXML::XML::Node instance with the provided name.

### Signature
`new_node(name) -> Object`

### Parameters
- **name** (String) - The name of the XML node to be created.
```

--------------------------------

### to_binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFString

Converts the string to binary format.

```APIDOC
## to_binary(bplist)

### Description
Converts the current string value to binary format using the provided binary property list object.

### Parameters
- **bplist** (Object) - Required - The binary property list handler instance.
```

--------------------------------

### Load XML from file or data

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser

Loads XML content from either a file path or a raw data string, returning the parsed root element.

```ruby
# File 'lib/cfpropertylist/rbLibXMLParser.rb', line 14

def load(opts)
  doc = nil

  if(opts.has_key?(:file)) then
    doc = LibXML::XML::Document.file(opts[:file],:options => PARSER_OPTIONS)
  else
    doc = LibXML::XML::Document.string(opts[:data],:options => PARSER_OPTIONS)
  end

  if doc
    root = doc.root.first
    return import_xml(root)
  end
rescue LibXML::XML::Error => e
  raise CFFormatError.new('invalid XML: ' + e.message)
end
```

--------------------------------

### CFPropertyList::Binary#load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary%3Aload

Reads a binary plist file or data from the provided options. Raises a CFFormatError if the file format is invalid.

```APIDOC
## CFPropertyList::Binary#load(opts)

### Description
Reads a binary plist file or data stream and returns the parsed object.

### Signature
`load(opts) ⇒ Object`

### Parameters
- **opts** (Hash) - Required - A hash containing either a `:file` key (path to the file) or a `:data` key (binary data string).

### Raises
- **CFFormatError** - Raised if the binary plist format is invalid or cannot be parsed.

### Returns
- **Object** - The parsed property list object.
```

--------------------------------

### Array#to_plist(options = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/Array%3Ato_plist

Converts an array to plist format. The method accepts an optional hash to specify formatting options, such as the plist format.

```APIDOC
## Array#to_plist

### Description
Converts a Ruby Array instance into a Property List (plist) formatted string.

### Method Signature
`to_plist(options = {}) -> Object`

### Parameters
- **options** (Hash) - Optional - Configuration options for the conversion. 
  - **:plist_format** - The desired format for the output (defaults to `CFPropertyList::List::FORMAT_BINARY`).

### Returns
- **Object** - A string representation of the array in plist format.
```

--------------------------------

### Create a new XML node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ReXMLParser

Instantiates a new REXML element with the specified name.

```ruby
# File 'lib/cfpropertylist/rbREXMLParser.rb', line 56

def new_node(name)
  REXML::Element.new(name)
end
```

--------------------------------

### Initialize CFDate object

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDate%3Ainitialize

Initializes a new CFDate instance by converting the provided value to a Time object or using a specified format.

```ruby
def initialize(value = nil,format=CFDate::TIMESTAMP_UNIX)
  if(value.is_a?(Time) || value.nil?) then
    @value = value.nil? ? Time.now : value
  elsif value.instance_of? Date
    @value = Time.utc(value.year, value.month, value.day, 0, 0, 0)
  elsif value.instance_of? DateTime
    @value = value.to_time.utc
  else
    set_value(value,format)
  end
end
```

--------------------------------

### CFPropertyList::List#load_str

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_str

Loads a plist from a string. If no string or format is provided, it defaults to the instance's internal data and format.

```APIDOC
## CFPropertyList::List#load_str

### Description
Loads a property list from a string. This method parses the input string based on the specified format or attempts to auto-detect the format if not provided.

### Method
Ruby Method

### Signature
`load_str(str = nil, format = nil) -> Object`

### Parameters
- **str** (String) - Optional - The string containing the plist data. If nil, defaults to the instance's internal data.
- **format** (Integer) - Optional - The format of the plist. If nil, defaults to the instance's internal format.
```

--------------------------------

### Define PARSER_OPTIONS constant

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser

Defines the default parser options for LibXML, disabling blank nodes and network access.

```ruby
LibXML::XML::Parser::Options::NOBLANKS|LibXML::XML::Parser::Options::NONET
```

--------------------------------

### Create a new REXML element

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/ReXMLParser%3Anew_node

Instantiates a new REXML::Element object with the specified name.

```ruby
def new_node(name)
  REXML::Element.new(name)
end
```

--------------------------------

### Convert string to binary format

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFString

Uses the provided bplist object to convert the current string value to binary.

```ruby
def to_binary(bplist)
  bplist.string_to_binary(@value);
end
```

--------------------------------

### Enumerator#to_plist(options = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/Enumerator%3Ato_plist

Converts an enumerator to plist format. The method accepts an optional hash of options to configure the output format.

```APIDOC
## Enumerator#to_plist

### Description
Converts an enumerator to plist format.

### Method
Ruby Method

### Parameters
- **options** (Hash) - Optional - Configuration options for the conversion. Defaults to an empty hash. The :plist_format key can be used to specify the output format (e.g., CFPropertyList::List::FORMAT_BINARY).

### Returns
- **Object** - The plist representation of the enumerator.
```

--------------------------------

### CFPropertyList::LibXMLParser#new_text(val)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Anew_text

Creates a new LibXML text node with the provided value.

```APIDOC
## new_text(val)

### Description
Creates a new LibXML text node using the provided value.

### Parameters
- **val** (Object) - Required - The value to be used for the new text node.

### Returns
- **Object** - Returns a new LibXML::XML::Node instance.
```

--------------------------------

### Convert CFInteger to binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFInteger%3Ato_binary

Converts the current CFInteger instance to a binary format using the specified bplist handler.

```ruby
def to_binary(bplist)
  bplist.num_to_binary(self)
end
```

--------------------------------

### CFPropertyList::List#load_plain

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_plain

Reads a plain plist file. If no filename is provided, it defaults to the filename stored in the instance variable.

```APIDOC
## CFPropertyList::List#load_plain

### Description
Reads a plain plist file into the CFPropertyList::List object.

### Signature
`load_plain(filename = nil) -> Object`

### Parameters
- **filename** (String) - Optional - The path to the plist file to be read. If nil, the method uses the filename defined by the instance variable.
```

--------------------------------

### CFPropertyList::List#formatted

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aformatted

Retrieves the current setting for XML generation formatting. If true, the generated XML will be formatted.

```APIDOC
## Method: CFPropertyList::List#formatted

### Description
Returns the default value for XML generation. If the returned value is true, the library will generate formatted XML output.

### Signature
`formatted ⇒ Object`

### Defined in
`lib/cfpropertylist/rbCFPropertyList.rb`
```

--------------------------------

### CFPropertyList::List#load_xml

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_xml

Loads an XML PropertyList from a file. If no filename is provided, it defaults to the filename stored in the instance variable.

```APIDOC
## CFPropertyList::List#load_xml

### Description
Loads an XML PropertyList from the specified file. If the filename argument is nil, the method reads from the file defined by the instance variable `filename`.

### Method
Ruby Method

### Signature
`load_xml(filename = nil) -> Object`

### Parameters
- **filename** (String) - Optional - The path to the XML file to be loaded.
```

--------------------------------

### CFPropertyList::LibXMLParser#load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Aload

Parses an XML file or XML data string into a CFPropertyList object structure.

```APIDOC
## Method: CFPropertyList::LibXMLParser#load

### Description
Reads and parses an XML file or raw XML data string. Returns the imported XML structure.

### Signature
`load(opts) -> Object`

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - Optional: The path to the XML file to load.
  - **:data** (String) - Optional: The raw XML data string to parse.

### Returns
- **Object** - The parsed and imported XML structure.
```

--------------------------------

### Create New XML Node

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/NokogiriXMLParser

Creates a new XML element node.

```ruby
# File 'lib/cfpropertylist/rbNokogiriParser.rb', line 60

def new_node(name)
  @doc.create_element name
end
```

--------------------------------

### Hash#to_plist(options = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/Hash%3Ato_plist

Converts a Ruby Hash object into a plist formatted string. The method accepts an optional hash of parameters to configure the output format.

```APIDOC
## Hash#to_plist

### Description
Converts a hash to plist format.

### Parameters
- **options** (Hash) - Optional - Configuration options for the conversion. 
  - **:plist_format** (Constant) - The format of the plist (defaults to CFPropertyList::List::FORMAT_BINARY).

### Returns
- **Object** - A string representation of the hash in plist format.
```

--------------------------------

### CFPropertyList::CFArray#initialize

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFArray%3Ainitialize

Initializes a new CFArray object. This method is called when creating a new instance of the class.

```APIDOC
## initialize(val = [])

### Description
Creates a new CFArray object. This method initializes the internal value of the array.

### Parameters
- **val** (Array) - Optional - The initial value for the CFArray, defaults to an empty array.

### Returns
- **CFArray** - A new instance of the CFArray class.
```

--------------------------------

### CFPropertyList::CFDictionary#to_binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary%3Ato_binary

Converts the CFDictionary instance to binary format using the specified bplist handler.

```APIDOC
## Method: to_binary(bplist)

### Description
Converts the current CFDictionary instance to a binary representation.

### Parameters
- **bplist** (Object) - Required - The binary property list handler object used to perform the conversion.

### Returns
- **Object** - The binary representation of the dictionary.
```

--------------------------------

### Initialize CFType

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFType

Constructor for creating a new instance of CFType with an optional value.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 33

def initialize(value=nil)
  @value = value
end
```

--------------------------------

### Load XML data using LibXMLParser

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/LibXMLParser%3Aload

Parses XML content provided via the :file or :data option. Raises a CFFormatError if the XML is invalid.

```ruby
def load(opts)
  doc = nil

  if(opts.has_key?(:file)) then
    doc = LibXML::XML::Document.file(opts[:file],:options => PARSER_OPTIONS)
  else
    doc = LibXML::XML::Document.string(opts[:data],:options => PARSER_OPTIONS)
  end

  if doc
    root = doc.root.first
    return import_xml(root)
  end
rescue LibXML::XML::Error => e
  raise CFFormatError.new('invalid XML: ' + e.message)
end
```

--------------------------------

### new_node(name)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/XMLParserInterface%3Anew_node

Creates a new node with the specified name.

```APIDOC
## new_node(name)

### Description
Creates a new node with the specified name.

### Signature
`new_node(name) ⇒ Object`

### Parameters
- **name** (Object) - The name of the node to be created.
```

--------------------------------

### CFPropertyList::CFInteger#to_binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFInteger%3Ato_binary

Converts the CFInteger instance to a binary format using the specified bplist handler.

```APIDOC
## CFPropertyList::CFInteger#to_binary

### Description
Converts the current CFInteger object to binary format.

### Method
Instance Method

### Parameters
- **bplist** (Object) - Required - The binary property list handler used to perform the conversion.
```

--------------------------------

### to_xml(parser)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFUid

Converts the UID value to XML format using the provided parser.

```APIDOC
## to_xml(parser)

### Description
Converts the UID value to XML format, wrapping it in a CFDictionary with a 'CF$UID' key.

### Parameters
- **parser** (Object) - Required - The XML parser instance.
```

--------------------------------

### CFPropertyList::CFDictionary#to_plain

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary%3Ato_plain

Converts the dictionary instance into a plain text string representation.

```APIDOC
## CFPropertyList::CFDictionary#to_plain

### Description
Converts the current CFDictionary instance into a plain text string representation, typically used for property list serialization.

### Method
Instance Method

### Parameters
- **plist** (Object) - Required - The property list context or configuration object used during conversion.

### Returns
- **String** - The plain text representation of the dictionary.
```

--------------------------------

### Load binary property list string

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_binary_str

This method parses a binary plist string. It requires the input string to be in a valid binary property list format.

```ruby
def load_binary_str(str=nil)
  load_str(str,List::FORMAT_BINARY)
end
```

--------------------------------

### to_plain(plist)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFArray

Converts the CFArray instance to a plain text representation.

```APIDOC
## to_plain(plist)

### Description
Converts the CFArray instance into a plain text string representation.

### Parameters
- **plist** (Object) - Required - The property list context used for conversion.
```

--------------------------------

### Convert CFArray to binary format

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFArray%3Ato_binary

This method delegates the conversion of the current CFArray instance to the provided bplist object.

```ruby
def to_binary(bplist)
  bplist.array_to_binary(self)
end
```

--------------------------------

### Serialize to plain text

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFType

Interface method for plain text serialization.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 43

def to_plain(plist)
end
```

--------------------------------

### CFPropertyList::NokogiriXMLParser#load(opts)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/NokogiriXMLParser%3Aload

Reads and parses an XML file or data string into a CFPropertyList object structure.

```APIDOC
## load(opts)

### Description
Reads a XML file or parses XML data provided in the options hash.

### Parameters
- **opts** (Hash) - Required
  - **:file** (String) - Optional - The filename of the file to load.
  - **:data** (String) - Optional - The raw XML data to parse.

### Returns
- **Object** - The parsed CFPropertyList object structure.
```

--------------------------------

### Retrieve PropertyList format

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aformat

Returns the format attribute of the CFPropertyList::List instance.

```ruby
# File 'lib/cfpropertylist/rbCFPropertyList.rb', line 218

def format
  @format
end
```

--------------------------------

### CFPropertyList::List#value

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Avalue

Returns the root value of the plist file.

```APIDOC
## CFPropertyList::List#value

### Description
Returns the root value stored in the plist file.

### Signature
`value() -> Object`
```

--------------------------------

### Save CFPropertyList object to file

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Asave

Serializes the object to the specified format and writes it to the provided file path. If file or format arguments are nil, the method defaults to the instance's stored filename and format.

```ruby
def save(file=nil,format=nil,opts={})
  format = @format if format.nil?
  file = @filename if file.nil?

  if format != FORMAT_BINARY && format != FORMAT_XML && format != FORMAT_PLAIN
    raise CFFormatError.new("Format #{format} not supported, use List::FORMAT_BINARY or List::FORMAT_XML")
  end

  if(!File.exist?(file)) then
    raise IOError.new("File #{file} not writable!") unless File.writable?(File.dirname(file))
  elsif(!File.writable?(file)) then
    raise IOError.new("File #{file} not writable!")
  end

  opts[:root] = @value
  opts[:formatted] = @formatted unless opts.has_key?(:formatted)

  prsr = @@parsers[format-1].new

  content = prsr.to_str(opts)

  File.open(file, 'wb') {
    |fd|
    fd.write content
  }
end
```

--------------------------------

### Convert CFDictionary to binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary%3Ato_binary

Uses the provided bplist object to perform the binary conversion of the dictionary.

```ruby
def to_binary(bplist)
  bplist.dict_to_binary(self)
end
```

--------------------------------

### Load XML String in CFPropertyList

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_xml_str

Parses a property list from the provided XML string. If no string is provided, it defaults to nil.

```ruby
def load_xml_str(str=nil)
  load_str(str,List::FORMAT_XML)
end
```

--------------------------------

### to_xml(parser)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFDictionary

Converts the dictionary instance to an XML representation using the provided parser.

```APIDOC
## to_xml(parser)

### Description
Converts the dictionary to XML format.

### Parameters
- **parser** (Object) - Required - The parser object used to generate XML nodes.
```

--------------------------------

### Convert UID to Binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary%3Auid_to_binary

Converts a given UID value into a binary format and stores it in the object table. This method handles signed and unsigned integers by determining the appropriate byte length.

```ruby
def uid_to_binary(value)
  nbytes = 0
  nbytes = 1  if value > 0xFF # 1 byte integer
  nbytes += 1 if value > 0xFFFF # 4 byte integer
  nbytes += 1 if value > 0xFFFFFFFF # 8 byte integer
  nbytes = 3  if value < 0 # 8 byte integer, since signed

  @object_table[@written_object_count] = Binary.type_bytes(0b1000, nbytes) <<
    if nbytes < 3
      [value].pack(
        if nbytes == 0    then "C"
        elsif nbytes == 1 then "n"
        else "N"
        end
      )
    else
      # 64 bit signed integer; we need the higher and the lower 32 bit of the value
      high_word = value >> 32
      low_word = value & 0xFFFFFFFF
      [high_word,low_word].pack("NN")
    end

  @written_object_count += 1
  @written_object_count - 1
end
```

--------------------------------

### to_plain(plist)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFUid

Converts the UID value to a plain format representation.

```APIDOC
## to_plain(plist)

### Description
Converts the UID value to a plain format, wrapping it in a CFDictionary with a 'CF$UID' key.

### Parameters
- **plist** (Object) - Required - The property list context.
```

--------------------------------

### Pack integer with specified byte size

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary.pack_it_with_size

Packs an integer into a binary format based on the provided byte count. Raises a CFFormatError if the byte size is not supported.

```ruby
def Binary.pack_it_with_size(nbytes,int)
  case nbytes
  when 1 then [int].pack('c')
  when 2 then [int].pack('n')
  when 4 then [int].pack('N')
  when 8
    [int >> 32, int & 0xFFFFFFFF].pack('NN')
  else
    raise CFFormatError.new("Don't know how to pack #{nbytes} byte integer")
  end
end
```

--------------------------------

### CFPropertyList::Binary#to_str(opts = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary%3Ato_str

Converts the CFPropertyList object to a binary string representation. It handles object counting and unique table generation for CFDictionary and CFArray types.

```APIDOC
## CFPropertyList::Binary#to_str

### Description
Converts the CFPropertyList object to a binary format (bplist00). This method performs object counting and unique table generation for CFDictionary and CFArray types to prepare the binary structure.

### Method
Ruby Method

### Signature
`to_str(opts = {})`

### Parameters
- **opts** (Hash) - Optional - Configuration options for the conversion, specifically supporting a :root key.

### Returns
- **Object** - A binary string representing the property list.
```

--------------------------------

### CFPropertyList::CFReal#to_binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFReal%3Ato_binary

Converts the CFReal instance to a binary format using the specified bplist handler.

```APIDOC
## Method: CFPropertyList::CFReal#to_binary

### Description
Converts the current CFReal object to binary format.

### Signature
`to_binary(bplist) -> Object`

### Parameters
- **bplist** (Object) - The binary property list handler used to perform the conversion.
```

--------------------------------

### CFPropertyList.guess(object, options = {})

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList.guess

Creates a CFType hierarchy by guessing the correct CFType for the provided Ruby object. It supports various Ruby types and provides options for handling unknown object types.

```APIDOC
## CFPropertyList.guess(object, options = {})

### Description
Creates a CFType hierarchy by guessing the correct CFType for the provided Ruby object. This method recursively processes arrays and hashes to build a complete CFType structure.

### Parameters
- **object** (Object) - Required - The Ruby object to convert into a CFType.
- **options** (Hash) - Optional - Configuration options for the conversion process.
    - **convert_unknown_to_string** (Boolean) - If true, converts unknown objects to strings using to_s().
    - **converter_method** (Symbol) - The name of a method to call on unknown objects to convert them to a known type.
    - **converter_with_opts** (Boolean) - If true, passes the options hash to the converter_method.

### Returns
- **Object** - The resulting CFType hierarchy.

### Example
```ruby
x = { 'a' => ['b','c','d'] }
cftypes = CFPropertyList.guess(x)

# With options
cftypes = CFPropertyList.guess(x, :convert_unknown_to_string => true, :converter_method => :to_hash, :converter_with_opts => true)
```
```

--------------------------------

### Unpack binary data with size

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/Binary%3Aunpack_with_size

Unpacks a buffer of binary data using a format string determined by the provided byte size. Special handling is applied when nbytes is 3 to pad the buffer.

```ruby
def unpack_with_size(nbytes, buff)
  format = ["C*", "n*", "N*", "N*"][nbytes - 1];

  if nbytes == 3
    buff = "\0" + buff.scan(/.{1,3}/).join("\0")
  end

  return buff.unpack(format)
end
```

--------------------------------

### CFPropertyList::CFString#to_binary

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFString%3Ato_binary

Converts the CFString instance to binary format using the specified bplist handler.

```APIDOC
## CFPropertyList::CFString#to_binary

### Description
Converts the current CFString instance to a binary representation.

### Method
Instance Method

### Parameters
- **bplist** (Object) - Required - The binary property list handler used to perform the conversion.

### Returns
- **Object** - The binary representation of the string.
```

--------------------------------

### to_xml(parser)

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFData

Converts the data to an XML node.

```APIDOC
## to_xml(parser)

### Description
Converts the current data object to an XML node using the provided parser.
```

--------------------------------

### Define new_text method in XMLParserInterface

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/XMLParserInterface%3Anew_text

This method is defined in lib/cfpropertylist/rbCFPropertyList.rb and currently contains no implementation.

```ruby
def new_text(val)
end
```

--------------------------------

### Serialize to XML

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFType

Interface method for XML serialization.

```ruby
# File 'lib/cfpropertylist/rbCFTypes.rb', line 37

def to_xml(parser)
end
```

--------------------------------

### Convert Array to Plist

Source: https://www.rubydoc.info/gems/CFPropertyList/Array%3Ato_plist

Converts the array instance to a plist string. Defaults to binary format if no format is specified in the options.

```ruby
def to_plist(options={})
  options[:plist_format] ||= CFPropertyList::List::FORMAT_BINARY

  plist = CFPropertyList::List.new
  plist.value = CFPropertyList.guess(self, options)
  plist.to_str(options[:plist_format], options)
end
```

--------------------------------

### to_plain

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/CFString

Converts the string to a plain text representation.

```APIDOC
## to_plain(plist)

### Description
Returns the string as plain text. If the string contains non-word characters, it returns the quoted version of the string.

### Parameters
- **plist** (Object) - Required - The property list context.
```

--------------------------------

### Load plist from string

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Aload_str

Parses a property list string into the object's value. Supports explicit format specification or automatic format detection.

```ruby
def load_str(str=nil,format=nil)
  str = @data if str.nil?
  format = @format if format.nil?

  @value = {}
  case format
  when List::FORMAT_BINARY, List::FORMAT_XML, List::FORMAT_PLAIN then
    prsr = @@parsers[format-1].new
    @value = prsr.load({:data => str})

  when List::FORMAT_AUTO then # what we now do is ugly, but neccessary to recognize the file format
    filetype = str[0..5]
    version = str[6..7]

    prsr = nil

    if filetype == "bplist" then
      raise CFFormatError.new("Wrong file version #{version}") unless version == "00"
      prsr = Binary.new
      @format = List::FORMAT_BINARY
    else
      if str =~ /^<(\?xml|!DOCTYPE|plist)/
        prsr = CFPropertyList.xml_parser_interface.new
        @format = List::FORMAT_XML
      else
        prsr = PlainParser.new
        @format = List::FORMAT_PLAIN
      end
    end

    @value = prsr.load({:data => str})
  end
end
```

--------------------------------

### CFPropertyList::PlainParser#to_str

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/PlainParser%3Ato_str

Serializes a CFPropertyList object to XML. The method accepts an options hash to control output formatting.

```APIDOC
## Method: to_str(opts = {})

### Description
Serializes a CFPropertyList object to XML.

### Parameters
- **opts** (Hash) - Optional - Configuration options for serialization.
  - **:formatted** (Boolean) - Optional - If set to true, uses indentation and line breaks in the output.

### Returns
- **Object** - The serialized XML representation of the CFPropertyList object.
```

--------------------------------

### CFPropertyList::List#save

Source: https://www.rubydoc.info/gems/CFPropertyList/CFPropertyList/List%3Asave

Serializes the CFPropertyList object to the specified format and writes it to the provided file path.

```APIDOC
## CFPropertyList::List#save

### Description
Serializes the CFPropertyList object to a specified format and writes the resulting data to a file.

### Signature
`save(file = nil, format = nil, opts = {})`

### Parameters
- **file** (String) - Optional - The path to the file to write to. If nil, uses the instance's `filename` variable.
- **format** (Integer) - Optional - The format to save in (e.g., FORMAT_BINARY, FORMAT_XML, FORMAT_PLAIN). If nil, uses the instance's `format` variable.
- **opts** (Hash) - Optional - Additional options for the serialization process.

### Returns
- **Object** - Returns the result of the file write operation.
```
Tokens:
Raw