Fixed server, improved docs

* made docs server compile again
 * improved migrating documenattion
 * improved CSS for mobile devices
 * fixed GitHub link

config.nims

@@ -61,7 +61,7 @@ task documentation, "Generate documentation":
     exec r"nim rst2html -o:../docout/testing.html testing.rst"
     exec r"nim rst2html -o:../docout/schema.html schema.rst"
     exec r"nim rst2html -o:../docout/migrating.html migrating.rst"
-    exec "cp docutils.css style.css processing.svg ../docout"
+    exec "cp docutils.css style.css processing.svg github-mark-white.svg ../docout"
   exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml"
   for file in listFiles("yaml"):
     let packageName = file[5..^5]

doc/github-mark-white.svg

@@ -0,0 +1 @@
+<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#fff"/></svg>

doc/migrating.rst

@@ -5,6 +5,22 @@ Migrating to NimYAML 2.x
 NimYAML 2.0.0 introduces some breaking changes, existing code likely needs to be updated.
 This document details the changes and describes what needs to be done to migrate existing code.
 
+Motivation
+==========
+
+NimYAML 2.0.0 is a release made for Nim 2.0.
+It drops support for earlier Nim versions and introduces features added in Nim 2.0, mainly default values for object fields.
+
+The second goal of NimYAML 2.0.0 was to make dumping YAML simpler and more useful.
+Previously, the default style for writing out YAML used exotic features like directives (e.g. ``%YAML 1.2``) and tags.
+This style has originally been chosen to closely follow the YAML specification's intentions of using YAML to share data between applications.
+However, the major usage for YAML today is configuration files.
+To better cater to this use-case, the dumping API has been redesigned to emit less talkative YAML by default.
+
+Finally, the signatures of API functions for dumping have been modified so that you can define your desired dumping style once in a ``Dumper`` object and then use that everywhere.
+This demotes exotic features like custom tag handles from direct parameters of API functions to fields in the ``Dumper`` object.
+This design also enables NimYAML to introduce more dumper options in the future without altering the API.
+
 Module Changes
 ==============
 

doc/style.css

@@ -1,21 +1,25 @@
-header {
+h1.title {
-    position: fixed;
+  margin-top: .5em;
-    top: 0;
+  margin-bottom: .5em;
-    left: 0;
+  padding-bottom: .5em;
-    right: 0;
-    height: 50px;
-    background: #111;
-    margin: 0;
-    padding: 0;
-    z-index: 1;
 }
 
-header a {
+header {
-    display: inline-block;
+    position: sticky;
-    line-height: 50px;
+    display: flex;
+    flex-wrap: wrap;
+    background: #111;
+    margin: 0;
+    padding: 0 .5em;
+    top: 0;
+    z-index: 1;
     font-size: large;
-    padding-left: 5px;
+}
-    padding-right: 5px;
+
+header > a {
+    display: block;
+    flex-grow: 0;
+    padding: .8em .2em;
 }
 
 header a.active {
@@ -23,16 +27,20 @@ header a.active {
     color: black !important;
 }
 
-header span {
+header > span {
-    display: inline-block;
+    display: block;
-    line-height: 50px;
+    flex-grow: 0;
     font-size: large;
     color: white;
-    padding-left: 15px;
+    padding: .8em .2em;
-    padding-right: 5px;
+    padding-left: .6em;
 }
 
-header span a {
+header > span.space {
+  flex-grow: 1;
+}
+
+header > span > a {
     display: block;
 }
 
@@ -43,6 +51,7 @@ header span ul {
     list-style: none;
     background: #111;
     margin: 0;
+    padding-bottom: .5em;
 }
 
 header span ul:after {
@@ -54,8 +63,8 @@ header span:hover > ul {
 }
 
 header span ul a {
-    padding: 0 10px;
+    padding: 0 .8em;
-    line-height: 40px;
+    line-height: 1.8em;
 }
 
 header span ul.monospace a {
@@ -91,10 +100,7 @@ a.pagetitle:visited {
 }
 
 body {
-    margin-left: 0;
+    margin: 0;
-    margin-right: 0;
-    margin-top: 55px;
-    margin-bottom: 5px;
     padding: 0;
 }
 
@@ -104,16 +110,16 @@ html {
 
 /* necessary for links to scroll to the right position */
 dt a:before {
-    margin-top: -50px;
+    margin-top: -2em;
-    height: 50px;
+    height: 2em;
     content: ' ';
     display: block;
     visibility: hidden;
 }
 
 #testingground {
-    margin-left: -50px;
+    margin-left: -2em;
-    margin-right: -50px;
+    margin-right: -2em;
 }
 
 #testingground textarea {
@@ -175,6 +181,8 @@ object {
 }
 
 /* hide autogenerated stuff we don't need */
-.theme-switch-wrapper, #global-links, #searchInputDiv {
+.theme-select-wrapper, #global-links, #searchInputDiv,
+#searchInputDiv + div /* this is the group by section */
+{
   display: none;
 }

flake.nix

@@ -43,20 +43,6 @@
                   cp -r src/* $out/lib
                 '';
               };
-              nim-cligen = pkgs.stdenv.mkDerivation {
-                name = "nim-cligen-0.15.3";
-                src = pkgs.fetchFromGitHub {
-                  owner = "c-blake";
-                  repo = "cligen";
-                  rev = "v1.5.23";
-                  sha256 = "rcledZbmcAXs0l5uQRmOennyMiw4G+zye6frGqksjyA=";
-                };
-                dontBuild = true;
-                installPhase = ''
-                  mkdir -p $out/lib
-                  cp -rt $out/lib cligen.nim cligen
-                '';
-              };
             in pkgs.stdenv.mkDerivation {
               pname = "nimyaml-server-deamon";
               inherit version;
@@ -77,7 +63,7 @@
                     ./rstPreproc -o:tmp.rst $txtFile
                     ${pkgs.nim2}/bin/nim rst2html -o:../docout/''${txtFile%.txt}.html tmp.rst
                   done
-                  cp docutils.css style.css processing.svg ../docout
+                  cp docutils.css style.css processing.svg github-mark-white.svg ../docout
                 )
                 ${pkgs.nim2}/bin/nim doc2 -o:docout/api/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/${
                   self.rev or "master"
@@ -94,7 +80,7 @@
                 proc shareDir*(): string =
                   result = "$out/share"
                 EOF
-                ${pkgs.nim2}/bin/nim c --d:release --stackTrace -p:"${nim-jester}/lib" -p:"${nim-httpbeast}/lib" -p:"${nim-cligen}/lib" --nimcache:.cache server/server
+                ${pkgs.nim2}/bin/nim c --stackTrace -p:"${nim-jester}/lib" -p:"${nim-httpbeast}/lib" --gc:refc --nimcache:.cache server/server
               '';
               installPhase = ''
                 mkdir -p $out/{bin,share}

nimdoc.cfg

@@ -103,11 +103,10 @@ doc.file = """
   <link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
 </head>
 <body>
-<a href="https://github.com/flyx/NimYAML"><img style="position: fixed; top: 0; right: 0; border: 0; z-index: 10;" src="https://camo.githubusercontent.com/652c5b9acfaddf3a9c326fa6bde407b87f7be0f4/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6f72616e67655f6666373630302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>
 <header>
-  <a class="pagetitle" href="/index.html">NimYAML</a>
+  <a class="pagetitle" href="/index.html">NimYAML</a></span>
-  <a href="/index.html">Home</a>
+  <span><a href="/index.html">Home</a></span>
-  <a href="/testing.html">Testing Ground</a>
+  <span><a href="/testing.html">Testing Ground</a></span>
   <span>Docs:</span>
   <a href="/api.html">Overview</a>
   <span>
@@ -117,9 +116,6 @@ doc.file = """
       <li><a href="/schema.html">Schema</a></li>
     </ul>
   </span>
-  <span>
-    <a href="/migrating.html">Migrating to NimYAML 2.x</a>
-  </span>
   <span>
     <a href="/api/yaml.html">Modules</a>
     <ul class="monospace">
@@ -138,6 +134,15 @@ doc.file = """
       <li><a href="/api/tojson.html">yaml/tojson</a></li>
     </ul>
   </span>
+  <span>
+    <a href="/migrating.html">NimYAML 2.x</a>
+  </span>
+  <span class="space"></span>
+  <span>
+    <a href="https://github.com/flyx/NimYAML">
+      <img src="/github-mark-white.svg" style="width: 1.5em; height: 1.5em; margin-bottom: -.2em; padding-right: .2em; margin-top: -.5em;" /> Source on GitHub
+    </a>
+  </span>
 </header>
 <article id="documentId">
   <div class="container">
@@ -147,7 +152,7 @@ doc.file = """
       <div class="twelve-columns footer">
         <span class="nim-sprite"></span>
         <br/>
-        <small>Made with Nim. Generated: $date $time UTC</small>
+        <small>Made with Nim.</small>
       </div>
     </div>
   </div>

server/server.nim

@@ -4,29 +4,29 @@
 #    See the file "copying.txt", included in this
 #    distribution, for details about the copyright.
 
-import jester, cligen, asyncdispatch, json, streams, strutils
+import jester, parseopt, asyncdispatch, json, streams, strutils
 import packages/docutils/rstgen, packages/docutils/highlite, options
-import ../yaml, server_cfg
+import ../yaml, ../yaml/parser, ../yaml/presenter, server_cfg
 
 router nyRouter:
   get "/webservice/":
     resp(Http200, [("Content-Type", "text/plain")], "I am a friendly NimYAML parser webservice.")
   post "/webservice/":
     var
-      style: PresentationStyle
       resultNode = newJObject()
       msg: string
       retStatus = Http200
       contentType = "application/json"
       headers = @[("Access-Control-Allow-Origin", "*"), ("Pragma", "no-cache"),
         ("Cache-Control", "no-cache"), ("Expires", "0")]
+      dumper: Dumper
     try:
       case @"style"
-      of "minimal": style = psMinimal
+      of "minimal": dumper.setMinimalStyle()
-      of "canonical": style = psCanonical
+      of "canonical": dumper.setCanonicalStyle()
-      of "default": style = psDefault
+      of "default": dumper.setDefaultStyle()
-      of "json": style = psJson
+      of "json": dumper.setJsonStyle()
-      of "block": style = psBlockOnly
+      of "block": dumper.setBlockOnlyStyle()
       of "tokens":
         try:
           var
@@ -48,7 +48,7 @@ router nyRouter:
         var
           output = newStringStream()
           highlighted = ""
-        transform(newStringStream(@"input"), output, defineOptions(style), true)
+        dumper.transform(newStringStream(@"input"), output, true)
 
         # syntax highlighting (stolen and modified from stlib's rstgen)
         var g: GeneralTokenizer
@@ -86,10 +86,29 @@ router nyRouter:
     headers.add(("Content-Type", contentType))
     resp retStatus, headers, msg
 
-proc main(port = 5000, address = "127.0.0.1") =
+proc main(port: int, address: string) =
   let settings = newSettings(port=port.Port, bindAddr=address, staticDir=shareDir())
   var jester = initJester(nyrouter, settings=settings)
   jester.serve()
 
 when isMainModule:
-  dispatch(main)
+  var
+    port = 5000
+    address = "127.0.0.1"
+  for kind, key, value in getOpt():
+    case kind
+    of cmdArgument:
+      echo "unexpected positional argument"
+      quit 1
+    of cmdLongOption, cmdShortOption:
+      case key
+      of "p", "port":
+        port = parseInt(value)
+      of "a", "address":
+        address = value
+      else:
+        echo "Unknown option: ", key
+        quit 1
+    of cmdEnd:
+      discard
+  main(port, address)

yaml/dumping.nim

@@ -13,7 +13,7 @@
 ## forms the highest-level API of NimYAML.
 
 import std/streams
-import presenter, native, private/internal
+import parser, presenter, native, private/internal
 export native
 
 type
@@ -129,4 +129,33 @@ proc dump*[K](
   var events = represent(value, dumper.serialization)
   try: result = present(events, dumper.presentation)
   except YamlStreamError as e:
-    internalError("Unexpected exception: " & $e.name)
+    internalError("Unexpected exception: " & $e.name)
+
+proc transform*(
+  dumper : Dumper,
+  input  : Stream | string,
+  output : Stream,
+  resolveToCoreYamlTags: bool = false,
+) {.raises: [
+  IOError, OSError, YamlParserError, YamlPresenterJsonError,
+  YamlPresenterOutputError
+].} =
+  ## Parse ``input`` as YAML character stream and then dump it to ``output``
+  ## using the given presentation options.
+  ## If ``resolveToCoreYamlTags`` is ``true``, non-specific tags will
+  ## be replaced by specific tags according to the YAML core schema.
+  transform(input, output, dumper.presentation, resolveToCoreYamlTags)
+
+proc transform*(
+  dumper : Dumper,
+  input  : Stream | string,
+  resolveToCoreYamlTags: bool = false,
+): string {.raises: [
+  IOError, OSError, YamlParserError, YamlPresenterJsonError,
+  YamlPresenterOutputError
+].} =
+  ## Parse ``input`` as YAML character stream and then dump it
+  ## using the given presentation options. Returns the resulting string.
+  ## If ``resolveToCoreYamlTags`` is ``true``, non-specific tags will
+  ## be replaced by specific tags according to the YAML core schema.
+  result = transform(input, dumper.presentation, resolveToCoreYamlTags)

yaml/presenter.nim

@@ -851,9 +851,9 @@ proc transform*(
   IOError, OSError, YamlParserError, YamlPresenterJsonError,
   YamlPresenterOutputError
 ].} =
-  ## Parser ``input`` as YAML character stream and then dump it to ``output``
+  ## Parse ``input`` as YAML character stream and then dump it to ``output``
-  ## while resolving non-specific tags to the ones in the YAML core tag
+  ## using the given presentation options.
-  ## library. If ``resolveToCoreYamlTags`` is ``true``, non-specific tags will
+  ## If ``resolveToCoreYamlTags`` is ``true``, non-specific tags will
   ## be replaced by specific tags according to the YAML core schema.
   var c = Context(target: output, options: options)
   doTransform(c, genInput(input), resolveToCoreYamlTags)
@@ -866,11 +866,10 @@ proc transform*(
   IOError, OSError, YamlParserError, YamlPresenterJsonError,
   YamlPresenterOutputError
 ].} =
-  ## Parser ``input`` as YAML character stream, resolves non-specific tags to
+  ## Parse ``input`` as YAML character stream and then dump it
-  ## the ones in the YAML core tag library, and then returns a serialized
+  ## using the given presentation options. Returns the resulting string.
-  ## YAML string that represents the stream. If ``resolveToCoreYamlTags`` is
+  ## If ``resolveToCoreYamlTags`` is ``true``, non-specific tags will
-  ## ``true``, non-specific tags will be replaced by specific tags according to
+  ## be replaced by specific tags according to the YAML core schema.
-  ## the YAML core schema.
   var
     ss = newStringStream()
     c = Context(target: ss, options: options)