Windows Errors & Crashes

[maksimkim]

Hello Daniel,

I'm trying to use your project for pretty printing our Blueprint API specs. In the head of master I'm getting the following error:

c:\dev\3dparty\aglio>aglio -i example.md -o output.html { code: 2, message: 'unexpected list block, expected a group, resource or an action definition, e.g. \'# Group \', \'# []\' or \'# \'', location: [] }

[danielgtaylor]

@maksimkim is there any way that you can share your API Blueprint or a subset of it that exhibits this issue? If not on here then perhaps privately with me so that I can come up with a test case to put into the aglio example blueprint to fix and prevent this error in the future?

I'm also curious - does your blueprint work if you copy/paste it into apiblueprint.org? It looks to me like you are getting an error from snowcrash, which is the library that parses the API Blueprint into JSON before rendering into HTML even begins.

[maksimkim]

I'm getting this error on sample spec from your repository -- example.md.

[maksimkim]

And one more note -- I'm working in Windows 8. So first thing I do before calling aglio is removing all '\r', cause with this chars in text aglio fails.

[danielgtaylor]

I believe the line ending issue can be solved with a git config:

https://help.github.com/articles/dealing-with-line-endings#platform-windows

As for the error, I'm working on better error and warning output for the next release. Is there any chance you could point me somewhere to get this running on Windows if I have a freshly installed Win8 VM? Node itself is easy, but what about the compiler for snowcrash/protagonist?

It does seem like a protagonist error, so it might be worth opening an issue there as well: https://github.com/apiaryio/protagonist and maybe pinging @zdne

[maksimkim]

To install your package on windows I've done the following steps: 1) install nodejs (npm included in installer) 2) install python 2.7 (higher releases are not suitable to some of your dependecies) and add path to python.exe to PATH enviroment variable 3) install visual studio 2012 express for windows desktop (some package requires c++ compiler) http://download.microsoft.com/download/1/F/5/1F519CC5-0B90-4EA3-8159-33BFB97EF4D9/wdexpress_full.exe

[zdne]

@danielgtaylor

The example in your repository does not seems to be 100% valid. See https://app.apiary.io/download/editor?from=https://raw.github.com/danielgtaylor/aglio/master/example.md

However I am not getting the error @maksimkim mentions.

@maksimkim can you paste here the exact blueprint that gives you the error if it is different to Example.md?

You can also try it at http://apiblueprint.org – just paste it there into the example area. Both Apiary and apiblueprint.org are using the latest Protagonist.

[zdne]

As for the line endings. This is an issue in the Snow Crash parser. Or more precisely in the underlaying Markdown parser – Sundown. I would eventually love to resolve it migrating to Hoedown.

However there is a lot of work to be done in Hoedown before this can happen - hoedown/hoedown#22 and hoedown/hoedown#28

[arbus]

@maksimkim I too faced the same issue on windows and resolved it like so:

In the initial npm install, you need to point node-gyp to your 2012 version of visual studio like so: npm install --msvs-version=2012

Next, replace all instances of \r with \n like so:

var fs = require('fs'), aglio = require('aglio');
fs.readFile('api.md', 'utf8', function (err,fileContents) {
  if (err) {
    return console.log(err);
  }
  aglio.render(fileContents.replace(/\r/g, '\n'), 'default', function (err,html) {
    if(err){
      return console.log(err);
    } 
    fs.writeFileSync('api.html', html);
  });
});

[maksimkim]

Ok. Here is full action sequence on my Windows 8.1. machine (python, vs2012, and ENVVAR's are installed):

1) git clone https://github.com/danielgtaylor/aglio.git

2) cd aglio

3) npm install

4) grunt

5) node bin\aglio.js -i example.md -o out.html

ERROR: 
{ code: 2,
  message: 'the use of carriage return(s) \'\\r\' in source data isn\'t currently supported, please contact makers',
  location: [ { index: 10, length: 1 } ] }

6) Open example.md in my text editor and replace all '\r' to ''.

7) node bin\aglio.js -i example.md -o out.html

ERROR:
{ code: 2,
  message: 'unexpected list block, expected a group, resource or an action definition, e.g. \'# Group <name>\', \'# <resource name> [<URI>]\' or \'# <HTTP method> <URI>\'',
  location: [] }

8) Add to aglio folder my sample API spec mkim.md that seems to be valid for app.apiary.io online editor:

FORMAT: 1A
HOST: https://sample

# sampleapi
Sample API

# Group User management
Resource related to user account management

## User collection [/users]
### List all users [GET]
+ Response 200 (application/json)

        [{
            "id": "mkim",
            "email": "mkim@sample.com", 
            "firstName": "Maxim",
            "lastName": "Kim"
        }, { ... }
        ]

### Register new user account [POST]
+ Request (application/json)

            {
                "email": "mkim@sample.com", 
                "firstName": "Maksim",
                "lastName": "Kim",
                "password": "cheburator"
            }

+ Response 201
    + Headers

            Location: https://sample

9) node bin\aglio.js -i mkim.md -o out.html

ERROR:
{ code: 1,
  message: 'parser exception has occured',
  location: [] }

I can add any additional diagnostic steps if you want

[danielgtaylor]

Okay, I've got this setup and working in a Windows VM and I'm able to reproduce the errors (and others). I am unable to get it working properly however. I've created an upstream issue:

https://github.com/apiaryio/protagonist/issues/4

[zdne]

@danielgtaylor thanks for investigating! I will proceed with the protagonist issue. And keep you posted there.

[danielgtaylor]

@maksimkim @arbus @EvgenyGusev: Everything should be fixed by 1d84c3a69aab4202fe94abc9a89344db7f610d4a in the latest release (1.10.0). Please give it a try and reopen this issue if there are still problems. You should no longer require any hacks and everything should just work out of the box.

[EvgenyGusev]

Thank you, now everything work!