<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="_c74_vig.xsl" type="text/xsl"?>
<vignette name="The Dict Object" package="Max">
	<h1>The Dict Object</h1>
	<p>
		The Dict object in JS is a companion to the <o>dict</o> object you create in a Max patcher.
		It provides the ability to access structured data (a dictionary) associated with a name.
	</p>


	<h2>Dict Constructor</h2>

	<code language="javascript">var d = new Dict("name");</code>
	<p>
		If no name is provided as an argument then a unique name will be generated for the dictionary.
	</p>

	The following properties mirror the attributes of the same name from the Max <o>dict</o> object.
	See the <o>dict</o> reference for more details.
	<jsproperty_list name="Dict">
    	<jsproperty name="name" get="1" set="1" type="symbol">
        	<description>
          	  Access or set the name of a dict object as a property of the dict object
        	</description>
    	</jsproperty>
    	<jsproperty name="quiet" get="1" set="1" type="boolean" default="false">
        	<description>
          	  The quiet property functions the same as the @quiet attribute to dict in Max. It suppresses many errors or warnings if set to true.
        	</description>
    	</jsproperty>
    </jsproperty_list>

    <jsmethod_list name="Dict">
  		<jsmethod name="append">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    	<arg name="value" type="list" />
		    </arglist>
		    <description>
		      Add values to the end of an array associated with the specified key.
		    </description>
  		</jsmethod>

  		<jsmethod name="clear">
		    <arglist>
		    </arglist>
		    <description>
		      Erase the contents of the dictionary, restoring to a clean state.
		    </description>
  		</jsmethod>

  		<jsmethod name="clone">
		    <arglist>
		    	<arg name="name" type="symbol"/>
		    </arglist>
		    <description>
		      Make a clone of the incoming dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="contains">
		    <arglist>
		    	<arg name="key" type="symbol"/>
		    </arglist>
		    <description>
		      Return a 0 or 1 indicating the specified key exists (or doesn't) in the dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="get">
		    <arglist>
		    	<arg name="key" type="symbol"/>
		    </arglist>
		    <description>
		      Return the value associated with a key.
		    </description>
  		</jsmethod>

  		<jsmethod name="getkeys">
		    <description>
		      Return a list of all the keys in a dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="getnames">
		    <description>
		      Return a list of all the dictionaries that currently exist.
		    </description>
  		</jsmethod>

  		<jsmethod name="getsize">
		    <description>
		      Return the number of values associated with a key.
		    </description>
  		</jsmethod>

  		<jsmethod name="gettype">
		    <description>
		      Return the type of the values associated with a key.
		    </description>
  		</jsmethod>

  		<jsmethod name="parse">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    	<arg name="value" type="symbol" />
		    </arglist>
		    <description>
		      Replace the content of a dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="pull_from_coll">
		    <arglist>
		    	<arg name="coll-name" type="symbol" />
		    </arglist>
		    <description>
		      Pull the content of a named coll object into the dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="push_to_coll">
		    <arglist>
		    	<arg name="coll-name" type="symbol" />
		    </arglist>
		    <description>
		      Push the dictionary's content into a named coll object. The keys in the dictionary will become the
		      indices in the coll, and the values for those indices the values of the dictionary's keys.
		    </description>
  		</jsmethod>

  		<jsmethod name="readany">
		    <arglist>
		    	<arg name="filename" type="symbol" />
		    </arglist>
		    <description>
		      Read the dictionary contents from a file.
		    </description>
  		</jsmethod>

  		<jsmethod name="remove">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    </arglist>
		    <description>
		      Remove a key and its associated value from the dictionary.
		    </description>
  		</jsmethod>

  		<jsmethod name="replace">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    	<arg name="value" type="list" />
		    </arglist>
		    <description>
		      Set the value for a key to a specified value, creating heirarchy.
		    </description>
  		</jsmethod>

  		<jsmethod name="set">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    	<arg name="value" type="list" />
		    </arglist>
		    <description>
		      Set the value for a key to a specified value.
		    </description>
  		</jsmethod>

  		<jsmethod name="setparse">
		    <arglist>
		    	<arg name="key" type="symbol" />
		    	<arg name="value" type="list" />
		    </arglist>
		    <description>
		      Set the value for a key to dictionary content defined using JSON.
		    </description>
  		</jsmethod>

  		<jsmethod name="writeagain">
		    <description>
		      Open a save dialog to write the dictionary contents to a file.
		    </description>
  		</jsmethod>

  		<jsmethod name="stringify">
		    <description>
		      Return the content of the dictionary as a JSON string.
		    </description>
  		</jsmethod>

  		<jsmethod name="import_json">
		    <arglist>
		    	<arg name="filename" type="symbol" />
		    </arglist>
		    <description>
		      Read a file from disk in the JSON format.
		    </description>
  		</jsmethod>

  		<jsmethod name="export_json">
		    <arglist>
		    	<arg name="filename" type="symbol" />
		    </arglist>
		    <description>
		      Write a file to disk in the JSON format.
		    </description>
  		</jsmethod>

  		<jsmethod name="import_yaml">
		    <arglist>
		    	<arg name="filename" type="symbol" />
		    </arglist>
		    <description>
		    	Read a file from disk in the YAML format.
		    </description>
  		</jsmethod>

  		<jsmethod name="export_yaml">
		    <arglist>
		    	<arg name="filename" type="symbol" />
		    </arglist>
		    <description>
		    	Write a file to disk in the YAML format.
		    </description>
  		</jsmethod>
  	</jsmethod_list>

	<h2>Examples</h2>
	Example code can be found in the "js" tab of the <o>dict</o> help patcher.
</vignette>
