Orbit roadmap

[George Petsagourakis]

In github there was a talk about orbit having a bugfix release and then carrying on with a proper 5.2 release.

It was not clear which of the bugfixes should be included. It would be a good thing to see set them so that anyone interested can target them.

=== Open bugs at this time:

- https://github.com/keplerproject/orbit/issues/18 - test_routes.lua fails with lpeg > 0.10
This is something that should be solvable.

Personally, I can go ahead and make a pull request for the routes.lua to remove the re.lua and stick to lpeg only calls.
This, apart from making the whole file more unified in expressions and a little more verbose in reading through it, makes it faster by at least 25%.
Nevertheless the bug is still outstanding.

An interesting note is that there is no usage of the orbit.routes anywhere in the orbit's source code apart from the test_routes.lua which drives me to think about the purpose of its existence.
I am pretty sure that Mascharenas can give an answer on that but in the meantime there is no evidence of this being a release blocker issue.

- https://github.com/keplerproject/orbit/issues/17 - Rockspecs out of sync
This is a housekeeping issue and should be resolved as soon as we get other bugs out of the way.

- https://github.com/keplerproject/orbit/issues/9 - Adapt Makefile to directory structure
This a valid bug and it is easily fixed since the solution proposed works. I have it in my fork already.

- https://github.com/keplerproject/orbit/issues/5 - Impossible to retrieve number of rows in model table
As kognix stated in a comment to this issue, this is not really a bug. There are other ways to get the rows. Maybe this is an indication for a convenience improvement.

So as it is evident, there isn't much to solve to about releasing the bugfix release. It will mainly be about the test_routes.lua bug.

=== As for 5.2:

- markdown.lua is 5.1 only and I've yet to find any other markdown implementation to work with 5.2. This is a big blocker.
We should evaluate the Markdown implementations available, pick one and push work towards it so that we get a component to use in a 5.2 version of Orbit.
This also renders (:pun: or not) the makedoc.lua inside the docs/ as well as some of the examples unable to function.

- htmlify_func() uses setfenv/getfenv that are not available with 5.2. This is a blocker.
Mascharenas has suggested that it might be acceptable to htmlify the app's _ENV instead of providing a separate environment for the htmlified functions to run.

Personally I'd keep "one clear way to do things" and stick to either cosmo or lustache removing the htmlify from the source code.
Introducing a dependency would look better in my eyes instead of trying to support a way to generated HTML code within a framework.
In particular, supporting mustache templates would be a point of familiarity for newcomers since the bets are that they'll be familiar with them.
In case that this is the direction taken, it would be a nice to think about Orbit's ability to use various templating systems.

[steve donovan]

On Wed, Dec 4, 2013 at 11:06 AM, George Petsagourakis
<petsa...@gmail.com> wrote:
> This, apart from making the whole file more unified in expressions and a
> little more verbose in reading through it, makes it faster by at least 25%.

Seems like a win!

> - markdown.lua is 5.1 only and I've yet to find any other markdown
> implementation to work with 5.2. This is a big blocker.

There I can help you - LDoc has a cleaned-up version that works fine with 5.2:

https://github.com/stevedonovan/LDoc/blob/master/ldoc/markdown.lua

> We should evaluate the Markdown implementations available, pick one and push
> work towards it so that we get a component to use in a 5.2 version of Orbit.

If speed matters, then something like lua-discount is _very_ much
faster for large docs. In LDoc I tend to fall back to Markdown.lua,
but one can specify the markdown processor....

> Personally I'd keep "one clear way to do things" and stick to either cosmo
> or lustache removing the htmlify from the source code.

Personally I've always enjoyed htmtification, but the current auto-env
version tends to fail silently, since a tag 'tble' will render and
cause much heartbreak later. So in Orbiter I have a version where the
tags are explicitly declared. This is also in Penlight, see
http://stevedonovan.github.io/Penlight/api/topics/06-data.md.html#XML
and go to 'Generating XML with ‘xmlification’' subsection. (The
difference in implementation is that this generates a LOM XML
representation which is later pretty-printed; in theory it should be
faster but I've not done the tests ;))

The _ENV thing is solvable, except as Fabio notes, there are no
longer per-function environments but they are per-module. So the
htmlify module could have a custom environment.

steve d.

[Fabio Mascarenhas]

On Wed, Dec 4, 2013 at 7:06 AM, George Petsagourakis
<petsa...@gmail.com> wrote:
> === Open bugs at this time:
>
> - https://github.com/keplerproject/orbit/issues/18 - test_routes.lua fails
> with lpeg > 0.10
> This is something that should be solvable.

I think it might be broken even with LPEG 0.10... I cannot find
anything in LPEG's HISTORY about the ., but the change in LPEG 0.10
where predicates do not keep captures should mess up the &('/' / {'.'}
/ !.) pattern that I used. There is a workaround, but it is not very
pretty.

> Personally, I can go ahead and make a pull request for the routes.lua to
> remove the re.lua and stick to lpeg only calls.
> This, apart from making the whole file more unified in expressions and a
> little more verbose in reading through it, makes it faster by at least 25%.
> Nevertheless the bug is still outstanding.

If you already have a working non-RE version I would say go for it.

> An interesting note is that there is no usage of the orbit.routes anywhere
> in the orbit's source code apart from the test_routes.lua which drives me to
> think about the purpose of its existence.
> I am pretty sure that Mascharenas can give an answer on that but in the
> meantime there is no evidence of this being a release blocker issue.
>

Right now it is an optional part of the system, see

https://github.com/keplerproject/orbit/blob/master/samples/routes/hello.lua

for an example of how it should be used. The idea was for it to become
the default router at some point (replacing the current one that
relies on plain Lua patterns).

> - https://github.com/keplerproject/orbit/issues/5 - Impossible to retrieve
> number of rows in model table
> As kognix stated in a comment to this issue, this is not really a bug. There
> are other ways to get the rows. Maybe this is an indication for a
> convenience improvement.
>
> So as it is evident, there isn't much to solve to about releasing the bugfix
> release. It will mainly be about the test_routes.lua bug.

I think a bugfix 5.1 release should also fix the issue about the uses
of "require" that assume that the module is still using the "module"
function, so Orbit will work with the latest, Lua 5.2-compatible,
versions of the other packages.

> === As for 5.2:
>
> - markdown.lua is 5.1 only and I've yet to find any other markdown
> implementation to work with 5.2. This is a big blocker.
> We should evaluate the Markdown implementations available, pick one and push
> work towards it so that we get a component to use in a 5.2 version of Orbit.
> This also renders (:pun: or not) the makedoc.lua inside the docs/ as well as
> some of the examples unable to function.

markdown.lua is 5.1-only because of a couple of setfenv calls that
were easy to fix. A fixed version is attached (it still pollutes the
global environment with a markdown function on require "markdown", but
removing this is trivial). There is also
http://jgm.github.io/lunamark/, which depends on LPEG.

--
Fabio Mascarenhas

[George Petsagourakis]

On Wednesday, December 4, 2013 3:12:32 PM UTC+2, Fabio Mascarenhas wrote:

I think it might be broken even with LPEG 0.10... I cannot find
anything in LPEG's HISTORY about the ., but the change in LPEG 0.10
where predicates do not keep captures should mess up the &('/' / {'.'}
/ !.) pattern that I used. There is a workaround, but it is not very
pretty.

 

This is indeed caused by the change to the 'and predicate' to not return captures.
It would be good to see it being resolved. Whatever it was I tried didn't seem to work.

 

If you already have a working non-RE version I would say go for it.

 

Ok, will do probably in a couple of hours.

Right now it is an optional part of the system, see

https://github.com/keplerproject/orbit/blob/master/samples/routes/hello.lua

for an example of how it should be used. The idea was for it to become
the default router at some point (replacing the current one that
relies on plain Lua patterns).

 

Should one of them be kept around? Or let me paraphrase: Is it justifiable to have two routing methods?

markdown.lua is 5.1-only because of a couple of setfenv calls that
were easy to fix. A fixed version is attached (it still pollutes the
global environment with a markdown function on require "markdown", but
removing this is trivial). There is also
http://jgm.github.io/lunamark/, which depends on LPEG.

 

Unfortunately, lunamark has a slnunicode dependency that doesn't compile against 5.2 API.

[George Petsagourakis]

One more thing, there is a blog_config.lua inside the doc/**/ that doesn't quite fit in.
There doesn't seem to be a reference to it from the docs. Should it be removed?

[Ryan Pusztai]

On Wed, Dec 4, 2013 at 4:24 AM, steve donovan <steve.j...@gmail.com> wrote:

On Wed, Dec 4, 2013 at 11:06 AM, George Petsagourakis
<petsa...@gmail.com> wrote:
> This, apart from making the whole file more unified in expressions and a
> little more verbose in reading through it, makes it faster by at least 25%.

Seems like a win!

Agreed.

 

> - markdown.lua is 5.1 only and I've yet to find any other markdown
> implementation to work with 5.2. This is a big blocker.

There I can help you - LDoc has a cleaned-up version that works fine with 5.2:

https://github.com/stevedonovan/LDoc/blob/master/ldoc/markdown.lua

Seems like the way to go. 

 

> Personally I'd keep "one clear way to do things" and stick to either cosmo

> or lustache removing the htmlify from the source code.

Personally I've always enjoyed htmtification, but the current auto-env
version tends to fail silently, since a tag 'tble' will render and
cause much heartbreak later.  So in Orbiter I have a version where the
tags are explicitly declared. This is also in Penlight, see
http://stevedonovan.github.io/Penlight/api/topics/06-data.md.html#XML
and go to 'Generating XML with ‘xmlification’' subsection. (The
difference in implementation is that this generates a LOM XML
representation which is later pretty-printed; in theory it should be
faster but I've not done the tests ;))

I have many sites right now that use htmlify() and so I think it needs to be maintained.

I also have used both Orbits and Orbiters and I think the new version should work like Orbiter. The issues it causes during debug are very hard to find. Plus it allows for html elements that are not currently supported by Orbit's htmlify(). 

I hope this makes sense.

 

  The _ENV thing is solvable, except as Fabio notes, there are no
longer per-function environments but they are per-module. So the
htmlify module could have a custom environment.

Agreed, but I think switching to a better more error proof system that generates HTML would be great. Also I like the way Orbiters html pretty-prints the html in a way that is readable.

--

Regards,
Ryan

[George Petsagourakis]

On Wednesday, December 4, 2013 3:12:32 PM UTC+2, Fabio Mascarenhas wrote:

I think a bugfix 5.1 release should also fix the issue about the uses
of "require" that assume that the module is still using the "module"
function, so Orbit will work with the latest, Lua 5.2-compatible,
versions of the other packages.

So basically convert all orbit modules to table modules, removing the module() calls?

[Ryan Pusztai]

So I merged a pull request for what I think solves this. Here is the changes to see if that is what you are talking about.

https://github.com/keplerproject/orbit/pull/20/files

--

Regards,
Ryan 

[Fabio Mascarenhas]

Yep, and make sure require is always assigning to some local variable,
and is not relying on the old behavior of "module" of putting the
module's table in the global namespace.

--
Fabio Mascarenhas

[Fabio Mascarenhas]

Yes, no idea how it ended up there.

--
Fabio Mascarenhas

[Fabio Mascarenhas]

On Wed, Dec 4, 2013 at 12:53 PM, George Petsagourakis
<petsa...@gmail.com> wrote:
> On Wednesday, December 4, 2013 3:12:32 PM UTC+2, Fabio Mascarenhas wrote:
>> I think it might be broken even with LPEG 0.10... I cannot find
>> anything in LPEG's HISTORY about the ., but the change in LPEG 0.10
>> where predicates do not keep captures should mess up the &('/' / {'.'}
>> / !.) pattern that I used. There is a workaround, but it is not very
>> pretty.
>
> This is indeed caused by the change to the 'and predicate' to not return
> captures.
> It would be good to see it being resolved. Whatever it was I tried didn't
> seem to work.
>

The idea would be to split each rule that uses &('/' / {'.'} / !.) in
two, one with
&('/' / !.), the other with &'.'. That way the first rule is
guaranteed to not have a trailing dot, and the second is guaranteed to
have, and the "dot" parameter in the capture function is not
necessary. But if you have a cleaner solution that drops the RE
dependency completely I still say go for it.

--
Fabio Mascarenhas

[George Petsagourakis]

OK, now it can be fixed with a click of a button.

https://github.com/keplerproject/orbit/pull/21

[George Petsagourakis]

On Wednesday, December 4, 2013 6:58:16 PM UTC+2, Fabio Mascarenhas wrote:

The idea would be to split each rule that uses &('/' / {'.'} / !.) in
two, one with
&('/' / !.), the other with &'.'. That way the first rule is
guaranteed to not have a trailing dot, and the second is guaranteed to
have, and the "dot" parameter in the capture function is not
necessary. But if you have a cleaner solution that drops the RE
dependency completely I still say go for it.

I don't have a solution for it yet.
There is a pull request for dropping the RE from routes.lua at the moment here:
https://github.com/keplerproject/orbit/pull/22

[Ian McIntosh]

Since I lodged the original issue on Github:
https://github.com/keplerproject/orbit/issues/17
I just want want to offer my comments here...

Originally I had in mind that we should create a bugfix release for Orbit, ( with only Lua 5.1 support)  that included fixes from 2010 to date, for the benefit of anyone installing Orbit with a standard 5.1 Luarocks config, such that:

    - it would run the existing samples and tests without error
    - it would run the existing Orbit 2.2.0 codebase without error or need for modification
    - it would incorporate some minor improvements and doc corrections (as per current master)

Let's call this [[Orbit 2.2.1]]

Let's also remember that there are many existing Orbit solutions out there that depend on Lua 5.1 (still the default version on Ubuntu 12.04 apt-get) and a working Orbit 2.2 stack. We don't want to break them... we should embrace them :)

So... I'm working on an Orbit 2.2.1 "bugfix" release  (complete with rockspec, gh-pages and documentation changes) and will offer a pull request as soon as possible.

--============ END OF 5.1 ==================

It was clear that under Lua 5.2,  Orbit would have to be a different beast, whatever shape it takes.
As Fabio rightly points out ...
"htmlify as is is a lost cause in 5.2 unless you want to go the debug library route."

So a fully 5.2 compliant version of Orbit, perhaps [[Orbit 2.3.0]], will be incompatible with any existing Orbit 2.2 applications (and Lua 5.1). IMHO it should therefore be free from any 5.1 legacy requirements, and there should be no need for "version testing" within the code... (lack of setfenv or module functions, "_E" should be assumed).

Will contribute and help with testing of course... :-)

Cheers, Ian

--
You received this message because you are subscribed to the Google Groups "Kepler Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kepler-projec...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Ian McIntosh]

There is now a pull request on Github for a proposed new Orbit 2.2.1 bugfix release:

https://github.com/keplerproject/orbit/pull/23

All samples now working and cleaned-up documentation to match, including gh-pages.