diff --git a/doc/doctrees/environment.pickle b/doc/doctrees/environment.pickle index 2c6f895..af517f1 100644 Binary files a/doc/doctrees/environment.pickle and b/doc/doctrees/environment.pickle differ diff --git a/doc/doctrees/tutorials/custom_types.doctree b/doc/doctrees/tutorials/custom_types.doctree index 3e5532e..07a4768 100644 Binary files a/doc/doctrees/tutorials/custom_types.doctree and b/doc/doctrees/tutorials/custom_types.doctree differ diff --git a/doc/doctrees/tutorials/getting_started.doctree b/doc/doctrees/tutorials/getting_started.doctree index b1337e3..06c76f4 100644 Binary files a/doc/doctrees/tutorials/getting_started.doctree and b/doc/doctrees/tutorials/getting_started.doctree differ diff --git a/doc/html/_sources/tutorials/custom_types.txt b/doc/html/_sources/tutorials/custom_types.txt index 95de259..90a2b17 100644 --- a/doc/html/_sources/tutorials/custom_types.txt +++ b/doc/html/_sources/tutorials/custom_types.txt @@ -302,6 +302,7 @@ such as the color being white. representer.addRepresenter!Color(&representColor); auto resolver = new Resolver; + import std.regex; resolver.addImplicitResolver("!color", std.regex.regex("[0-9a-fA-F]{6}"), "0123456789abcdefABCDEF"); diff --git a/doc/html/_sources/tutorials/getting_started.txt b/doc/html/_sources/tutorials/getting_started.txt index 99cb834..d968fa8 100644 --- a/doc/html/_sources/tutorials/getting_started.txt +++ b/doc/html/_sources/tutorials/getting_started.txt @@ -1,13 +1,13 @@ =============== -Getting started +Getting started =============== -Welcome to D:YAML! D:YAML is a `YAML `_ -parser library for the `D programming language `_. -This tutorial will explain how to set D:YAML up and use it in your projects. +Welcome to D:YAML! D:YAML is a `YAML `_ parser +library for the `D programming language `_. This tutorial will +explain how to set D:YAML up and use it in your projects. -This is meant to be the **simplest possible** introduction to D:YAML. Some of -this information might already be known to you. Only basic usage is covered. +This is meant to be the **simplest possible** introduction to D:YAML. Some of this +information might already be known to you. Only basic usage is covered. ---------- @@ -18,59 +18,43 @@ Setting up Install the DMD compiler ^^^^^^^^^^^^^^^^^^^^^^^^ -Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can -find its newest version `here `_. -Download the version of DMD for your operating system and install it. +Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its +newest version `here `_. Download the version of DMD +for your operating system and install it. -.. note:: - Other D compilers exist, such as - `GDC `_ and +.. note:: + Other D compilers exist, such as + `GDC `_ and `LDC `_. -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Download and compile D:YAML -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^ +Install dub +^^^^^^^^^^^ -The newest version of D:YAML can be found -`here `_. Download a source archive, extract -it, and move to the extracted directory. +`dub `_ is a build system and package manager for D. +It is the standard way to manage D projects and their dependencies, compilation and so +on. -D:YAML uses a modified version of the `CDC `_ -script for compilation. To compile D:YAML, you first need to build CDC. -Do this by typing the following command into the console:: - - dmd cdc.d - -Now compile D:YAML with CDC. -To do this on Unix/Linux, use the following command:: - - ./cdc - -On Windows:: - - cdc.exe - -This will compile the library to a file called ``libdyaml.a`` on Unix/Linux or -``libdyaml.lib`` on Windows. +DMD may include DUB in future releases, but at this point we need to install it +separately. See +`installation instructions `_. ------------------------- -Your first D:YAML project +Your first D:YAML project ------------------------- -Create a directory for your project and in that directory, create a file called -``input.yaml`` with the following contents: +Create a directory for your project and in that directory, create a new file named +``input.yaml`` and paste this code into the file: .. code-block:: yaml - Hello World : - - Hello - - World + Hello World : [Hello, World] Answer: 42 This will serve as input for our example. -Now we need to parse it. Create a file called ``main.d``. Paste following code +Now we need to parse it. Create a new file with name ``main.d``. Paste following code into the file: .. code-block:: d @@ -99,83 +83,94 @@ into the file: Explanation of the code ^^^^^^^^^^^^^^^^^^^^^^^ -First, we import the *yaml* module. This is the only D:YAML module you -need to import - it automatically imports all needed modules. +First, we import the *dyaml.all* module. This is the only D:YAML module you need to +import - it automatically imports all needed modules. -Next we load the file using the *Loader.load()* method. *Loader* is a struct -used for parsing YAML documents. The *load()* method loads the file as -**one** YAML document, or throws *YAMLException*, D:YAML exception type, if the -file could not be parsed or does not contain exactly one document. Note that we -don't do any error checking here in order to keep the example as simple as -possible. +Next we load the file using the *Loader.load()* method. *Loader* is a struct used for +parsing YAML documents. The *load()* method loads the file as **one** YAML document, or +throws *YAMLException*, D:YAML exception type, if the file could not be parsed or +contains more than one document. Note that we don't do any error checking here in order +to keep the example as simple as possible. -*Node* represents a node in a YAML document. It can be a sequence (array), -mapping (associative array) or a scalar (value). Here the root node is a -mapping, and we use the index operator to get subnodes with keys "Hello World" -and "Answer". We iterate over the first, as it is a sequence, and use the -*Node.as()* method on the second to read its value as an integer. +*Node* represents a node in a YAML document. It can be a sequence (array), mapping +(associative array) or a scalar (value). Here the root node is a mapping, and we use the +index operator to get subnodes with keys "Hello World" and "Answer". We iterate over the +former, as it is a sequence, and use the *Node.as()* method on the latter to read its +value as an integer. -You can iterate over a mapping or sequence as if it was an associative or normal -array. If you try to iterate over a scalar, it will throw a *YAMLException*. +You can iterate over a mapping or sequence as if it was an associative or normal array, +respectively. If you try to iterate over a scalar, it will throw a *YAMLException*. -You can iterate over subnodes using *Node* as the iterated type, or specify -the type subnodes are expected to have. D:YAML will automatically convert -iterated subnodes to that type if possible. Here we specify the *string* type, -so we iterate over the "Hello World" sequence as an array of strings. If it is -not possible to convert to iterated type, a *YAMLException* is thrown. For -instance, if we specified *int* here, we would get an error, as "Hello" +You can iterate using *Node* as the iterated type, or specify the type iterated nodes +are expected to have. D:YAML will automatically convert to that type if possible. Here +we specify the *string* type, so we iterate over the "Hello World" sequence as an array +of strings. If it is not possible to convert to iterated type, a *YAMLException* is +thrown. For instance, if we specified *int* here, we would get an error, as "Hello" cannot be converted to an integer. -The *Node.as()* method is used to read value of a scalar node as specified type. -D:YAML will try to return the scalar as this type, converting if needed, -throwing *YAMLException* if not possible. +The *Node.as()* method is used to read value of a scalar node as specified type. If the +scalar does not have the specified type, D:YAML will try to convert it, throwing +*YAMLException* if not possible. -Finally we dump the document we just read to ``output.yaml`` with the -*Dumper.dump()* method. *Dumper* is a struct used to dump YAML documents. -The *dump()* method writes one or more documents to a file, throwing -*YAMLException* if the file could not be written to. +Finally we dump the document we just read to ``output.yaml`` with the *Dumper.dump()* +method. *Dumper* is a struct used to dump YAML documents. The *dump()* method writes +one or more documents to a file, throwing *YAMLException* if the file could not be +written to. -D:YAML doesn't preserve style information in documents, so even though -``output.yaml`` will contain the same data as ``input.yaml``, it might be -formatted differently. Comments are not preserved, either. +D:YAML tries to preserve style information in documents so e.g. ``[Hello, World]`` is +not turned into: + +| ``- Hello`` +| ``- World`` + +However, comments are not preserved and neither are any extra formatting whitespace that +doesn't affect the meaning of YAML contents. ^^^^^^^^^ Compiling ^^^^^^^^^ -To compile your project, DMD needs to know which directories contain the -imported modules and the library. You also need to tell it to link with D:YAML. -The import directory should be the ``source`` subdirectory of the D:YAML -directory. You can specify it using the ``-I`` option of DMD. The library -directory should point to the compiled library. On Unix/Linux you can specify -it using the ``-L-L`` option, and link with D:YAML using the ``-L-l`` option. -On Windows, the import directory is used as the library directory. To link with -the library on Windows, just add the path to it relative to the current -directory. +We're going to use dub, which we installed at the beginning, to compile our project. -For example, if you extracted and compiled D:YAML in ``/home/xxx/dyaml``, your -project is in ``/home/xxx/dyaml-project``, and you are currently in that -directory, compile the project with the following command on Unix/Linux:: +Create a file called ``dub.json`` with the following contents: - dmd -I../dyaml/source -L-L../dyaml -L-ldyaml main.d +.. code-block:: json -And the following on Windows:: + { + "name": "getting-started", + "targetType": "executable", + "sourceFiles": ["main.d"], + "mainSourceFile": "main.d", + "dependencies": + { + "dyaml": { "version" : "~>0.5.0", "path" : "../../"}, + }, + } - dmd -I../dyaml/source ../dyaml/libdyaml.lib main.d +This file tells dub that we're building an executable called ``getting-started`` from +a D source file ``main.d``, and that our project depends on D:YAML 0.5.0 or any newer, +bugfix release of D:YAML 0.5 . DUB will automatically find and download the correct +version of D:YAML when the project is built. -This will produce an executable called ``main`` or ``main.exe`` in your -directory. When you run it, it should produce the following output:: +Now run the following command in your project's directory:: + + dub build + +dub will automatically download D:YAML and compile it, and then then it will compile our +program. This will generate an executable called ``getting-started`` or +``getting-started.exe`` in your directory. When you run it, it should produce the +following output:: Hello World - The answer is 42 + The answer is 42 ^^^^^^^^^^ Conclusion ^^^^^^^^^^ -You should now have a basic idea about how to use D:YAML. To learn more, look at -the `API documentation <../api/index.html>`_ and other tutorials. You can find code for this +You should now have a basic idea about how to use D:YAML. To learn more, look at the +`API documentation <../api/index.html>`_ and other tutorials. You can find code for this example in the ``example/getting_started`` directory in the package. diff --git a/doc/html/searchindex.js b/doc/html/searchindex.js index a80c63a..0091a10 100644 --- a/doc/html/searchindex.js +++ b/doc/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({envversion:42,terms:{represent:2,all:[1,3,4],code:[1,3],representmap:3,scalar:[1,2,3,4],follow:[3,4],decid:3,"const":3,show:[0,3],readabl:0,representsequ:3,program:4,digit:[3,4],sourc:[3,4],everi:3,string:[0,3,4],powervr:0,"void":[3,4],phobo:1,failur:3,veri:1,implicitli:[0,3],tri:1,gender:0,iter:4,"try":[3,4],item:0,path:4,refer:[0,3],slower:0,past:4,fold:0,second:[0,4],design:0,pass:3,rrr:3,even:[1,4],index:4,what:3,appear:1,compar:3,cast:3,preserv:[0,4],section:3,current:4,version:4,"new":3,method:[3,4],dyaml:[1,4],never:1,here:4,ggg:3,ldyaml:4,depend:[0,3],modifi:4,sinc:3,valu:[0,1,3,4],convert:[0,3,4],male:0,loos:1,datetim:0,omap:0,chang:[0,1,3],commonli:4,modul:4,unix:4,subnod:4,articl:[0,2],regex:3,from:3,would:[3,4],doubl:0,two:[0,1],next:[3,4],few:1,call:[3,4],msg:3,type:[1,2],tell:4,more:[0,4],sort:3,main:[3,4],phone:0,hold:3,must:3,addrepresent:3,word:4,alia:[0,1],work:1,itself:3,can:[0,1,3,4],learn:4,purpos:3,root:[3,4],overrid:3,want:3,stream:[0,1],process:3,templat:3,topic:3,tag:[1,3,2],tab:1,serial:[0,3],addconstructorxxx:3,cours:3,multipl:[0,1],newlin:0,quot:[0,1],getting_start:4,how:[3,4],foreach:[3,4],subdirectori:4,answer:[0,4],instead:0,simpl:[0,3,4],css:3,map:[1,2,3,4],mar:4,clone:0,variant:1,befor:3,ff0000:3,uint:3,mai:1,end:[0,1],data:[1,2],ani:[0,3,4],stdio:4,explicit:[0,3],correspond:3,ambigu:1,caus:1,inform:[0,4],green:[0,3],allow:[0,1],first:[2,3],order:[1,4],over:4,move:4,orang:3,becaus:1,yamlexcept:[3,4],hierarchi:0,still:[0,1],paramet:3,write:4,style:[0,4],precondit:3,window:4,complex:[0,3],therefor:[1,3],might:[0,1,3,4],alter:3,them:[0,1,3],good:3,"return":[3,4],thei:[0,1,3],python:0,auto:3,now:[1,3,4],introduct:[0,4],name:0,separ:0,each:[0,3],found:[3,4],went:3,complet:3,mean:1,compil:3,unequ:1,idea:4,"static":3,expect:[3,4],our:[3,4],happen:3,extract:4,out:[0,3],space:0,content:[1,3,4],rel:4,"0123456789abcdefabcdef":3,ref:3,red:[0,3],difficulti:1,advanc:0,"0123456789abcdef":3,mystruct:3,reason:3,base:[0,3],dictionari:0,put:3,org:[1,3],"byte":1,thrown:[3,4],pyyaml:[0,1],indent:[0,1],could:[3,4],keep:4,length:3,yamlcoloninflowcontext:1,confus:1,assign:0,radeon:0,oper:[0,3,4],rang:3,onc:[0,1],arrai:[0,1,3,4],sometim:3,restrict:1,unlik:0,alreadi:[3,4],done:3,construct:[0,3],miss:3,addconstructormap:3,size:0,seq:0,script:4,associ:[0,1,4],addimplicitresolv:3,system:[0,4],messag:3,gpu:0,white:3,conveni:0,"final":[3,4],store:[0,3],adher:1,consol:4,option:[0,4],especi:0,ishexdigit:3,specifi:[0,3,4],pars:[0,3,4],somewhat:0,exactli:4,than:1,serv:4,remov:0,structur:[0,1],charact:[0,1,3],project:2,str:[0,3],were:3,argument:3,packag:[3,4],have:[0,3,4],tabl:0,need:[0,1,3,4],"null":0,lib:4,alias:[1,2],constructcolormap:3,note:[3,4],also:[0,3,4],read:[0,3,4],take:3,which:[0,1,3,4],brace:0,channel:3,uppercas:3,compat:3,begin:[0,1],normal:4,previou:3,most:[0,3,4],detect:3,pair:[0,3],"class":[1,3],don:[1,3,4],later:3,flow:[0,1],doe:[0,1,4],bracket:0,cortex:0,fact:0,cdc:4,alphanumer:1,syntax:2,identifi:[0,3],find:[3,4],onli:[3,4],explicitli:[0,3],just:[3,4],explain:4,should:[1,3,4],meant:4,std:[0,3,4],get:[2,3],express:3,cannot:[1,4],report:3,whether:3,common:0,contain:[0,1,3,4],where:[0,3],wiki:1,set:[2,3],dump:[3,4],"float":[0,3],see:[0,1,3],result:3,fail:1,close:1,athlon:0,representscalar:3,wikipedia:0,written:4,simplest:4,"import":[3,4],signatur:3,accord:1,kei:[0,1,4],both:3,last:0,howev:[0,3],equal:3,comment:[0,4],etc:3,tutori:[2,3,4],context:[0,1],load:[1,3,4],point:4,constructcolorscalar:3,hyphen:0,loader:[3,4],colon:0,suppli:3,respect:3,addconstructorscalar:3,rgb:3,empti:0,implicit:[0,3],json:0,basic:4,xxx:[3,4],anywher:0,assert:3,togeth:3,input:[3,4],"catch":3,multi:0,ident:3,look:4,plain:[0,1,3],ffff00:3,easier:0,defin:0,ain:0,error:4,anchor:[1,2],readi:3,non:[0,3],archiv:4,tediou:3,ascii:[1,3],dumper:[3,4],disabl:3,clearli:1,make:3,same:[0,1,3,4],binari:0,instanc:[1,3,4],timestamp:0,android:0,document:1,difficult:0,http:1,nest:0,blue:[0,3],user:[0,3],implement:[1,3],markup:0,well:3,person:0,exampl:[3,4],command:4,thi:[0,1,3,4],everyth:3,left:0,ldc:4,systim:0,newest:4,execut:4,less:1,paragraph:0,gdc:4,human:0,languag:[0,4],struct:[1,3,4],libdyaml:4,interptet:1,except:[3,4],color:[0,3],add:[3,4],other:[1,4],els:0,match:3,build:4,real:0,format:[0,3,4],handl:[1,3],know:[3,4],world:4,recurs:[0,1],tolow:3,like:3,success:3,arbitrari:3,resolv:2,integ:[0,3,4],arthur:0,api:[2,3,4],singl:[0,1],output:[3,4],unnecessari:1,right:1,linux:[0,4],some:[0,1,3,4],guarante:3,ubyt:[0,3],librari:4,representcolor:3,lead:1,though:4,per:3,unord:1,condit:3,duplic:3,either:[0,3,4],object:3,run:4,acronym:0,usag:4,immut:3,rrggbb:3,unicod:1,chapter:0,comparison:3,about:[1,4],rare:1,usedefaultrepresent:3,page:0,regular:3,constructor:2,fals:3,produc:4,block:0,subset:0,within:1,encod:1,automat:4,bbb:3,bsd:0,mark:[0,1],your:[2,3],wai:[1,3],support:[0,1,3],question:0,"long":0,custom:2,writeln:[3,4],start:[2,3],"function":3,form:3,continu:0,link:4,line:0,opcmp:3,"throw":[3,4],consist:0,possibl:[0,1,3,4],"default":[0,3],displai:4,until:0,directori:[3,4],problem:1,similar:0,featur:[0,1],creat:[0,3,4],"int":[0,3,4],cover:4,dure:3,parser:[0,4],doesn:4,repres:[0,3,4],"char":3,exist:4,file:[1,3,4],yamlnul:0,isdigit:3,dent:0,check:[3,4],probabl:0,hex:3,when:[3,4],detail:[0,1],invalid:3,field:3,valid:1,bool:0,futur:[0,1],test:3,you:[0,3,4],node:[0,3,4],resolut:[0,3],sequenc:[2,3,4],consid:1,debian:0,reduc:0,longer:3,home:4,rule:1,hello:4,ignor:1,far:3,escap:0,cpu:0},objtypes:{},objnames:{},filenames:["tutorials/yaml_syntax","articles/spec_differences","index","tutorials/custom_types","tutorials/getting_started"],titles:["YAML syntax","Differences between D:YAML and the YAML specification","Welcome to D:YAML documentation!","Custom YAML data types","Getting started"],objects:{},titleterms:{compil:4,represent:3,set:4,syntax:0,scalar:0,code:4,download:4,instal:4,your:4,differ:1,welcom:2,start:4,custom:3,yaml:[0,1,2,3,4],explan:4,between:1,document:[0,2],type:3,map:0,get:4,sequenc:0,known:1,data:3,conclus:4,dmd:4,specif:1,list:1,resolv:3,project:4,alias:0,tag:0,constructor:3,anchor:0,first:4}}) \ No newline at end of file +Search.setIndex({envversion:42,terms:{represent:[],all:[1,3,4],code:1,representmap:3,scalar:1,follow:[3,4],decid:3,"const":3,show:[0,3],readabl:0,representsequ:3,program:4,digit:[3,4],sourc:[3,4],everi:3,string:[0,3,4],powervr:0,"void":[3,4],phobo:1,failur:3,veri:1,affect:4,implicitli:[0,3],tri:[1,4],gender:0,iter:4,"try":[3,4],item:0,refer:[0,3],slower:0,past:4,fold:0,second:0,design:0,pass:3,rrr:3,even:1,index:4,what:3,appear:1,compar:3,cast:3,preserv:[0,4],section:3,current:[],version:4,"new":[3,4],method:[3,4],dyaml:[1,4],gener:4,never:1,here:4,ggg:3,ldyaml:[],depend:[0,3,4],modifi:[],sinc:3,valu:[0,1,3,4],convert:[0,3,4],male:0,loos:1,datetim:0,omap:0,chang:[0,1,3],commonli:4,extra:4,modul:4,releas:4,unix:[],subnod:4,home:[],articl:[0,2],regex:3,from:[3,4],would:[3,4],doubl:0,two:[0,1],next:[3,4],mainsourcefil:4,few:1,call:[3,4],handl:[1,3],msg:3,type:1,tell:4,more:[0,4],sort:3,phone:0,hold:3,must:3,addrepresent:3,word:4,alia:[0,1],work:1,itself:3,can:[0,1,3,4],learn:4,purpos:3,root:[3,4],overrid:3,sourcefil:4,stream:[0,1],process:3,templat:3,topic:3,tag:1,tab:1,serial:[0,3],addconstructorxxx:3,cours:3,multipl:[0,1],newlin:0,quot:[0,1],getting_start:4,how:[3,4],targettyp:4,foreach:[3,4],subdirectori:[],answer:[0,4],instead:0,simpl:[0,3,4],css:3,map:1,mar:4,clone:0,variant:1,befor:3,ff0000:3,uint:3,mai:[1,4],end:[0,1],data:1,stdio:4,explicit:[0,3],correspond:3,ambigu:1,caus:1,inform:[0,4],green:[0,3],allow:[0,1],first:[],order:[1,4],over:4,move:[],orang:3,becaus:1,yamlexcept:[3,4],hierarchi:0,still:[0,1],paramet:3,write:4,style:[0,4],precondit:3,window:[],complex:[0,3],main:[3,4],might:[0,1,3,4],alter:3,them:[0,1,3],good:3,"return":3,thei:[0,1,3],python:0,auto:3,now:[1,3,4],introduct:[0,4],name:[0,4],instruct:4,separ:[0,4],each:[0,3],found:3,went:3,complet:3,mean:[1,4],compil:[],unequ:1,idea:4,"static":3,expect:[3,4],our:[3,4],happen:3,extract:[],out:[0,3],space:0,content:[1,3,4],rel:[],"0123456789abcdefabcdef":3,ref:3,correct:4,red:[0,3],difficulti:1,advanc:0,"0123456789abcdef":3,mystruct:3,standard:4,reason:3,base:[0,3],dictionari:0,put:3,org:[1,3],"byte":1,thrown:[3,4],pyyaml:[0,1],indent:[0,1],could:[3,4],keep:4,turn:4,length:3,yamlcoloninflowcontext:1,confus:1,assign:0,radeon:0,oper:[0,3,4],rang:3,onc:[0,1],arrai:[0,1,3,4],sometim:3,restrict:1,unlik:0,alreadi:[3,4],done:3,construct:[0,3],miss:3,addconstructormap:3,size:0,seq:0,script:[],associ:[0,1,4],addimplicitresolv:3,system:[0,4],messag:3,gpu:0,white:3,conveni:0,"final":[3,4],store:[0,3],adher:1,consol:[],option:0,especi:0,ishexdigit:3,specifi:[0,3,4],pars:[0,3,4],somewhat:0,exactli:[],than:[1,4],serv:4,remov:0,structur:[0,1],charact:[0,1,3],project:[],str:[0,3],were:3,argument:3,packag:[3,4],have:[0,3,4],tabl:0,need:[0,1,3,4],"null":0,built:4,lib:[],alias:1,latter:4,constructcolormap:3,note:[3,4],also:[0,3],take:3,which:[0,1,3,4],brace:0,channel:3,uppercas:3,compat:3,begin:[0,1,4],normal:4,previou:3,most:[0,3,4],detect:3,pair:[0,3],"class":[1,3],don:[1,3,4],later:3,flow:[0,1],doe:[0,1,4],bracket:0,cortex:0,fact:0,cdc:[],alphanumer:1,syntax:[],identifi:[0,3],find:[3,4],onli:[3,4],explicitli:[0,3],just:[3,4],explain:4,should:[1,3,4],meant:4,std:[0,3,4],get:[],express:3,cannot:[1,4],report:3,whether:3,common:0,contain:[0,1,3,4],where:[0,3],wiki:1,set:[],dump:[3,4],"float":[0,3],see:[0,1,3,4],result:3,fail:1,close:1,athlon:0,representscalar:3,wikipedia:0,written:4,simplest:4,"import":[3,4],neither:4,signatur:3,accord:1,kei:[0,1,4],both:3,last:0,howev:[0,3,4],equal:3,comment:[0,4],etc:3,tutori:[2,3,4],context:[0,1],load:[1,3,4],point:4,constructcolorscalar:3,hyphen:0,loader:[3,4],colon:0,path:4,respect:[3,4],addconstructorscalar:3,rgb:3,empti:0,implicit:[0,3],json:[0,4],basic:4,xxx:3,ani:[0,3,4],assert:3,togeth:3,input:[3,4],"catch":3,former:4,multi:0,ident:3,look:4,plain:[0,1,3],ffff00:3,easier:0,defin:0,ain:0,error:4,anchor:1,readi:3,therefor:[1,3],non:[0,3],archiv:[],tediou:3,ascii:[1,3],dumper:[3,4],disabl:3,clearli:1,make:3,same:[0,1,3],binari:0,instanc:[1,3,4],timestamp:0,android:0,document:1,difficult:0,http:1,nest:0,blue:[0,3],user:[0,3],implement:[1,3],markup:0,well:3,person:0,exampl:[3,4],command:4,thi:[0,1,3,4],everyth:3,left:0,ldc:4,systim:0,newest:4,execut:4,less:1,paragraph:0,gdc:4,human:0,languag:[0,4],struct:[1,3,4],libdyaml:[],interptet:1,except:[3,4],color:[0,3],add:3,other:[1,4],els:0,match:3,build:4,real:0,format:[0,3,4],read:[0,3,4],know:3,world:4,recurs:[0,1],tolow:3,like:3,success:3,arbitrari:3,whitespac:4,resolv:[],integ:[0,3,4],arthur:0,api:[2,3,4],singl:[0,1],output:[3,4],unnecessari:1,right:1,linux:0,some:[0,1,3,4],guarante:3,ubyt:[0,3],librari:4,representcolor:3,lead:1,though:[],per:3,unord:1,condit:3,duplic:3,either:[0,3],object:3,run:4,acronym:0,usag:4,immut:3,rrggbb:3,unicod:1,chapter:0,comparison:3,about:[1,4],rare:1,usedefaultrepresent:3,page:0,regular:3,constructor:[],fals:3,produc:4,block:0,subset:0,within:1,encod:1,automat:4,bbb:3,bsd:0,mark:[0,1],your:[],manag:4,wai:[1,3,4],support:[0,1,3],question:0,"long":0,custom:[],writeln:[3,4],start:[],includ:4,"function":3,form:3,continu:0,link:[],newer:4,line:0,opcmp:3,suppli:3,"throw":[3,4],consist:0,possibl:[0,1,3,4],"default":[0,3],bugfix:4,displai:4,until:0,directori:[3,4],problem:1,similar:0,featur:[0,1],creat:[0,3,4],"int":[0,3,4],cover:4,dure:3,parser:[0,4],doesn:4,repres:[0,3,4],"char":3,exist:4,file:[1,3,4],yamlnul:0,isdigit:3,dent:0,check:[3,4],probabl:0,want:3,hex:3,when:[3,4],detail:[0,1],invalid:3,field:3,valid:1,bool:0,futur:[0,1,4],test:3,you:[0,3,4],node:[0,3,4],resolut:[0,3],sequenc:[],consid:1,debian:0,reduc:0,longer:3,anywher:0,rule:1,hello:4,ignor:1,far:3,escap:0,cpu:0},objtypes:{},objnames:{},filenames:["tutorials/yaml_syntax","articles/spec_differences","index","tutorials/custom_types","tutorials/getting_started"],titles:["YAML syntax","Differences between D:YAML and the YAML specification","Welcome to D:YAML documentation!","Custom YAML data types","Getting started"],objects:{},titleterms:{compil:4,represent:3,set:4,syntax:0,scalar:0,code:4,download:[],instal:4,your:4,differ:1,welcom:2,start:4,dub:4,custom:3,yaml:[0,1,2,3,4],explan:4,between:1,document:[0,2],type:3,map:0,get:4,sequenc:0,known:1,data:3,conclus:4,dmd:4,specif:1,list:1,resolv:3,project:4,alias:0,tag:0,constructor:3,anchor:0,first:4}}) \ No newline at end of file diff --git a/doc/html/tutorials/custom_types.html b/doc/html/tutorials/custom_types.html index 1bc5a3e..d5da2bc 100644 --- a/doc/html/tutorials/custom_types.html +++ b/doc/html/tutorials/custom_types.html @@ -306,6 +306,7 @@ such as the color being white.

representer.addRepresenter!Color(&representColor); auto resolver = new Resolver; + import std.regex; resolver.addImplicitResolver("!color", std.regex.regex("[0-9a-fA-F]{6}"), "0123456789abcdefABCDEF"); diff --git a/doc/html/tutorials/getting_started.html b/doc/html/tutorials/getting_started.html index 2ad0d55..bb2c425 100644 --- a/doc/html/tutorials/getting_started.html +++ b/doc/html/tutorials/getting_started.html @@ -48,18 +48,18 @@

Getting started

-

Welcome to D:YAML! D:YAML is a YAML -parser library for the D programming language. -This tutorial will explain how to set D:YAML up and use it in your projects.

-

This is meant to be the simplest possible introduction to D:YAML. Some of -this information might already be known to you. Only basic usage is covered.

+

Welcome to D:YAML! D:YAML is a YAML parser +library for the D programming language. This tutorial will +explain how to set D:YAML up and use it in your projects.

+

This is meant to be the simplest possible introduction to D:YAML. Some of this +information might already be known to you. Only basic usage is covered.

Setting up

Install the DMD compiler

-

Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can -find its newest version here. -Download the version of DMD for your operating system and install it.

+

Digital Mars D compiler, or DMD, is the most commonly used D compiler. You can find its +newest version here. Download the version of DMD +for your operating system and install it.

Note

Other D compilers exist, such as @@ -67,42 +67,26 @@ Download the version of DMD for your operating system and install it.

LDC.

-
-

Download and compile D:YAML

-

The newest version of D:YAML can be found -here. Download a source archive, extract -it, and move to the extracted directory.

-

D:YAML uses a modified version of the CDC -script for compilation. To compile D:YAML, you first need to build CDC. -Do this by typing the following command into the console:

-
dmd cdc.d
-
-
-

Now compile D:YAML with CDC. -To do this on Unix/Linux, use the following command:

-
./cdc
-
-
-

On Windows:

-
cdc.exe
-
-
-

This will compile the library to a file called libdyaml.a on Unix/Linux or -libdyaml.lib on Windows.

+
+

Install dub

+

dub is a build system and package manager for D. +It is the standard way to manage D projects and their dependencies, compilation and so +on.

+

DMD may include DUB in future releases, but at this point we need to install it +separately. See +installation instructions.

Your first D:YAML project

-

Create a directory for your project and in that directory, create a file called -input.yaml with the following contents:

-
Hello World :
-    - Hello
-    - World
+
Create a directory for your project and in that directory, create a new file named
+input.yaml and paste this code into the file:

+
Hello World : [Hello, World]
 Answer: 42
 

 

 
This will serve as input for our example.

-
Now we need to parse it. Create a file called main.d. Paste following code
+
Now we need to parse it. Create a new file with name main.d. Paste following code
 into the file:

 
import std.stdio;
 import yaml;
@@ -126,62 +110,70 @@ into the file:

 

 

 
Explanation of the code

-
First, we import the yaml module. This is the only D:YAML module you
-need to import - it automatically imports all needed modules.

-
Next we load the file using the Loader.load() method. Loader is a struct
-used for parsing YAML documents. The load() method loads the file as
-one YAML document, or throws YAMLException, D:YAML exception type, if the
-file could not be parsed or does not contain exactly one document. Note that we
-don’t do any error checking here in order to keep the example as simple as
-possible.

-
Node represents a node in a YAML document. It can be a sequence (array),
-mapping (associative array) or a scalar (value). Here the root node is a
-mapping, and we use the index operator to get subnodes with keys “Hello World”
-and “Answer”. We iterate over the first, as it is a sequence, and use the
-Node.as() method on the second to read its value as an integer.

-
You can iterate over a mapping or sequence as if it was an associative or normal
-array. If you try to iterate over a scalar, it will throw a YAMLException.

-
You can iterate over subnodes using Node as the iterated type, or specify
-the type subnodes are expected to have. D:YAML will automatically convert
-iterated subnodes to that type if possible. Here we specify the string type,
-so we iterate over the “Hello World” sequence as an array of strings. If it is
-not possible to convert to iterated type, a YAMLException is thrown. For
-instance, if we specified int here, we would get an error, as “Hello”
+
First, we import the dyaml.all module. This is the only D:YAML module you need to
+import - it automatically imports all needed modules.

+
Next we load the file using the Loader.load() method. Loader is a struct used for
+parsing YAML documents. The load() method loads the file as one YAML document, or
+throws YAMLException, D:YAML exception type, if the file could not be parsed or
+contains more than one document.  Note that we don’t do any error checking here in order
+to keep the example as simple as possible.

+
Node represents a node in a YAML document. It can be a sequence (array), mapping
+(associative array) or a scalar (value). Here the root node is a mapping, and we use the
+index operator to get subnodes with keys “Hello World” and “Answer”. We iterate over the
+former, as it is a sequence, and use the Node.as() method on the latter to read its
+value as an integer.

+
You can iterate over a mapping or sequence as if it was an associative or normal array,
+respectively.  If you try to iterate over a scalar, it will throw a YAMLException.

+
You can iterate using Node as the iterated type, or specify the type iterated nodes
+are expected to have. D:YAML will automatically convert to that type if possible. Here
+we specify the string type, so we iterate over the “Hello World” sequence as an array
+of strings. If it is not possible to convert to iterated type, a YAMLException is
+thrown. For instance, if we specified int here, we would get an error, as “Hello”
 cannot be converted to an integer.

-
The Node.as() method is used to read value of a scalar node as specified type.
-D:YAML will try to return the scalar as this type, converting if needed,
-throwing YAMLException if not possible.

-
Finally we dump the document we just read to output.yaml with the
-Dumper.dump() method. Dumper is a struct used to dump YAML documents.
-The dump() method writes one or more documents to a file, throwing
-YAMLException if the file could not be written to.

-
D:YAML doesn’t preserve style information in documents, so even though
-output.yaml will contain the same data as input.yaml, it might be
-formatted differently. Comments are not preserved, either.

+
The Node.as() method is used to read value of a scalar node as specified type.  If the
+scalar does not have the specified type, D:YAML will try to convert it, throwing
+YAMLException if not possible.

+
Finally we dump the document we just read to output.yaml with the Dumper.dump()
+method. Dumper is a struct used to dump YAML documents.  The dump() method writes
+one or more documents to a file, throwing YAMLException if the file could not be
+written to.

+
D:YAML tries to preserve style information in documents so e.g.  [Hello, World] is
+not turned into:

+

+
- Hello

+
- World

+

+
However, comments are not preserved and neither are any extra formatting whitespace that
+doesn’t affect the meaning of YAML contents.

 

 

 
Compiling

-
To compile your project, DMD needs to know which directories contain the
-imported modules and the library. You also need to tell it to link with D:YAML.
-The import directory should be the source subdirectory of the D:YAML
-directory. You can specify it using the -I option of DMD. The library
-directory should point to the compiled library. On Unix/Linux you can specify
-it using the -L-L option, and link with D:YAML using the -L-l option.
-On Windows, the import directory is used as the library directory. To link with
-the library on Windows, just add the path to it relative to the current
-directory.

-
For example, if you extracted and compiled D:YAML in /home/xxx/dyaml, your
-project is in /home/xxx/dyaml-project, and you are currently in that
-directory, compile the project with the following command on Unix/Linux:

-
dmd -I../dyaml/source -L-L../dyaml -L-ldyaml main.d
+
We’re going to use dub, which we installed at the beginning, to compile our project.

+
Create a file called dub.json with the following contents:

+
{
+    "name": "getting-started",
+    "targetType": "executable",
+    "sourceFiles": ["main.d"],
+    "mainSourceFile": "main.d",
+    "dependencies":
+    {
+        "dyaml": { "version" : "~>0.5.0", "path" : "../../"},
+    },
+}
 

 

-
And the following on Windows:

-
dmd -I../dyaml/source ../dyaml/libdyaml.lib main.d
+
This file tells dub that we’re building an executable called getting-started from
+a D source file main.d, and that our project depends on D:YAML 0.5.0 or any newer,
+bugfix release of D:YAML 0.5 . DUB will automatically find and download the correct
+version of D:YAML when the project is built.

+
Now run the following command in your project’s directory:

+
dub build
 

 

-
This will produce an executable called main or main.exe in your
-directory. When you run it, it should produce the following output:

+
dub will automatically download D:YAML and compile it, and then then it will compile our
+program.  This will generate an executable called getting-started or
+getting-started.exe in your directory.  When you run it, it should produce the
+following output:

 
Hello
 World
 The answer is 42
@@ -190,8 +182,8 @@ The answer is 42
 

 

 
Conclusion

-
You should now have a basic idea about how to use D:YAML. To learn more, look at
-the API documentation and other tutorials. You can find code for this
+
You should now have a basic idea about how to use D:YAML. To learn more, look at the
+API documentation and other tutorials. You can find code for this
 example in the example/getting_started directory in the package.

 

 

@@ -211,7 +203,7 @@ example in the example/getting_st
 
  • Getting started