Lua Style Guide ?

classic Classic list List threaded Threaded
96 messages Options
12345
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Hisham
On 8 June 2017 at 10:21, Dirk Laurie <[hidden email]> wrote:
> 2017-06-08 13:51 GMT+02:00 steve donovan <[hidden email]>:
>
>> Heh, but they had curly-braces to deal with, always a fine topic for
>> bikeshedding!
>
> Finally, the word emerges. I have been restraining myself, disciplining
> my fingers, choking it down, ever since this thread started, and there
> you go and just casually spit it out.

I've come to dislike this word more and more over the years, as it's
way too often used as a way to shut down conversations, in the style
of Godwin's Law. For all the discussions on syntax we've had over the
years on lua-l, I think this one was one of the best ones, especially
since (a) it is focused on actual Lua syntax, which has a limited
scope (and not proposed inventions, for which not even the sky is the
limit), and (b) it is discussed for what it is: style. Style is
important, and while it's hard to get good discussions on style that
go beyond "mine is better than yours", once people get past that point
one can get some good insights on what makes people's sense of style
tick, what are their rationales and especially to revisit and
reevaluate one's own. I learned some good stuff while reading other
people's style guides and writing my own!

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Dirk Laurie-2
2017-06-10 2:10 GMT+02:00 Hisham <[hidden email]>:

> On 8 June 2017 at 10:21, Dirk Laurie <[hidden email]> wrote:
>> 2017-06-08 13:51 GMT+02:00 steve donovan <[hidden email]>:
>>
>>> Heh, but they had curly-braces to deal with, always a fine topic for
>>> bikeshedding!
>>
>> Finally, the word emerges. I have been restraining myself, disciplining
>> my fingers, choking it down, ever since this thread started, and there
>> you go and just casually spit it out.
>
> I've come to dislike this word more and more over the years, as it's
> way too often used as a way to shut down conversations, in the style
> of Godwin's Law. For all the discussions on syntax we've had over the
> years on lua-l, I think this one was one of the best ones, especially
> since (a) it is focused on actual Lua syntax, which has a limited
> scope (and not proposed inventions, for which not even the sky is the
> limit), and (b) it is discussed for what it is: style. Style is
> important, and while it's hard to get good discussions on style that
> go beyond "mine is better than yours", once people get past that point
> one can get some good insights on what makes people's sense of style
> tick, what are their rationales and especially to revisit and
> reevaluate one's own. I learned some good stuff while reading other
> people's style guides and writing my own!

My main beef is that despite the title, there has been almost no
discussion of style (which means: among several ways of doing the
same task, pick one and always do it like that); it's all been about
prettyprinting: how many spaces, what about tabs. why not blank
lines instead, etc. You can no more get people to agree on that
than you can change their taste in music. A convention for indents
is vital for Python, but  Lua is not Python.

Put another way: if all that you are going to achieve is another
program with exactly the same compilable code, it just looks nicer,
fro a certain meaning of 'nice', I don't care what you did, I'm going
to run your code through my in-house reformatter anyway.

Non-trivial style means doing things in a certain way, every time,
so that others on the project (or yourself, next year) feel at home
with the code. Things like:

1. What will our 'require' return? A function? A table? A userdata?
2. Do we locally cache predefined globals?
3. How do we code sentinel objects (i.e values that like nil are
guaranteed not to be equal to anything else)?
4. Do we make big do ... end blocks in our code in order to
restrict the scope of locals?
5. Do we use some sort of Hungarian notation (i.e. CamelCase,
quick_brown_fox etc) that advertises what the name will be
used for)?
6. Do we consciously conform to ldoc rules for comments?

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
It was thus said that the Great Dirk Laurie once stated:
>
> Non-trivial style means doing things in a certain way, every time,
> so that others on the project (or yourself, next year) feel at home
> with the code. Things like:
>
> 1. What will our 'require' return? A function? A table? A userdata?

  For the most part, I return a table (a consequence of the Lua 5.1 module
system), although I do have modules that return a function [1] and some a
userdata [2].  Sometimes the module only has one function [3] and it seems
silly to return an entire table with just one function.  But with most Lua
modules returning a table, I can see an argument for always returning a
table.  

> 2. Do we locally cache predefined globals?

  Yes for modules, no for the main program.  When I do cache predefined
globals, how I do it depends upon what it is.  For example:

        local math         = require "math"
        local string       = require "string"
        local io           = require "io"
        local pairs        = pairs
        local tostring     = tostring
        local type         = type
        local print        = print
        local pcall        = pcall
        local getmetatable = getmetatable

  Yes, I tend to require() globals like io, string and table.  To me, it
signals the intent that I want the actual module and while

        local math = math

will work ... eh.  Showing intent is important as well, and this makes no
assumption as to what is loaded and not.  Granted, I can't require() global
functions like type() or pcall(), but if I could, I would.

> 3. How do we code sentinel objects (i.e values that like nil are
> guaranteed not to be equal to anything else)?

  This hasn't really come up with me, so I have no opinion on this.

> 4. Do we make big do ... end blocks in our code in order to
> restrict the scope of locals?

  I do that quite often.  In fact, I'll do things like:

        local somevar do
          -- code to do a bunch of stuff
          somevar = ...
        end

to make it clear that there is some non-trivial initialization of a local
variable.

> 5. Do we use some sort of Hungarian notation (i.e. CamelCase,
> quick_brown_fox etc) that advertises what the name will be
> used for)?

  Oh @#$@#$@ no.  I have to suffer with this at work (C and C++ code).  No
thank you.

> 6. Do we consciously conform to ldoc rules for comments?

  Personally, I don't quite care for ldoc [4] as it seems to require too
much typing.  I have my own way of doing it [5] but no way yet to
autogenerate documentation (but I am trying to keep the format consistent to
allow that at some point).

  -spc (There's also the whole namespace issue for modules, but no one seems
        interested in that bugaboo ... )

[1] https://github.com/spc476/lua-conmanorg/blob/master/src/base64.c
        https://github.com/spc476/lua-conmanorg/blob/master/src/pollset.c

        Some others that haven't been published yet.

[2] https://github.com/spc476/LPeg-Parsers

        These return LPeg expressions.

[3] https://github.com/spc476/lua-conmanorg/blob/master/lua/getopt.lua

[4] I'm checking the source code itself to LDoc and I'm not finding much
        in the way of LDoc in it.  It seems that only "public" methods have
        it, no local functions.

[5] As seen in here: https://github.com/spc476/CBOR/blob/master/cbor.lua

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Hisham
In reply to this post by Dirk Laurie-2
On 10 June 2017 at 01:18, Dirk Laurie <[hidden email]> wrote:

> 2017-06-10 2:10 GMT+02:00 Hisham <[hidden email]>:
>> On 8 June 2017 at 10:21, Dirk Laurie <[hidden email]> wrote:
>>> 2017-06-08 13:51 GMT+02:00 steve donovan <[hidden email]>:
>>>
>>>> Heh, but they had curly-braces to deal with, always a fine topic for
>>>> bikeshedding!
>>>
>>> Finally, the word emerges. I have been restraining myself, disciplining
>>> my fingers, choking it down, ever since this thread started, and there
>>> you go and just casually spit it out.
>>
>> I've come to dislike this word more and more over the years, as it's
>> way too often used as a way to shut down conversations, in the style
>> of Godwin's Law. For all the discussions on syntax we've had over the
>> years on lua-l, I think this one was one of the best ones, especially
>> since (a) it is focused on actual Lua syntax, which has a limited
>> scope (and not proposed inventions, for which not even the sky is the
>> limit), and (b) it is discussed for what it is: style. Style is
>> important, and while it's hard to get good discussions on style that
>> go beyond "mine is better than yours", once people get past that point
>> one can get some good insights on what makes people's sense of style
>> tick, what are their rationales and especially to revisit and
>> reevaluate one's own. I learned some good stuff while reading other
>> people's style guides and writing my own!
>
> My main beef is that despite the title, there has been almost no
> discussion of style (which means: among several ways of doing the
> same task, pick one and always do it like that); it's all been about
> prettyprinting: how many spaces, what about tabs. why not blank
> lines instead, etc. You can no more get people to agree on that
> than you can change their taste in music. A convention for indents
> is vital for Python, but  Lua is not Python.
>
> Put another way: if all that you are going to achieve is another
> program with exactly the same compilable code, it just looks nicer,
> fro a certain meaning of 'nice', I don't care what you did, I'm going
> to run your code through my in-house reformatter anyway.
>
> Non-trivial style means doing things in a certain way, every time,
> so that others on the project (or yourself, next year) feel at home
> with the code. Things like:
>
> 1. What will our 'require' return? A function? A table? A userdata?
> 2. Do we locally cache predefined globals?
> 3. How do we code sentinel objects (i.e values that like nil are
> guaranteed not to be equal to anything else)?
> 4. Do we make big do ... end blocks in our code in order to
> restrict the scope of locals?
> 5. Do we use some sort of Hungarian notation (i.e. CamelCase,
> quick_brown_fox etc) that advertises what the name will be
> used for)?
> 6. Do we consciously conform to ldoc rules for comments?

Did you follow the links for the various style guides posted? They
address these things. Mine specifically answers questions 1, 5 and 6.

For the other ones, my answers as far as the LuaRocks project goes
(because not every project has the same constraints) is:

2. No. This kind of micro-optimization should be avoided unless shown
to be measurably necessary (which is not the case in the LuaRocks
command-line tool).
3. In the rare event I needed this, I simply declared it as {}
4. No. Use short functions and modules.

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Hisham
In reply to this post by Sean Conner
On 10 June 2017 at 03:02, Sean Conner <[hidden email]> wrote:

>
> It was thus said that the Great Dirk Laurie once stated:
> > 4. Do we make big do ... end blocks in our code in order to
> > restrict the scope of locals?
>
>   I do that quite often.  In fact, I'll do things like:
>
>         local somevar do
>           -- code to do a bunch of stuff
>           somevar = ...
>         end
>
> to make it clear that there is some non-trivial initialization of a local
> variable.

Dirk talked about using do-end blocks to restrict the scope of locals,
but the above example with odd indentation does not do that.

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Daurnimator
In reply to this post by Dirk Laurie-2
On 10 June 2017 at 14:18, Dirk Laurie <[hidden email]> wrote:
> 1. What will our 'require' return? A function? A table? A userdata?

A table: I learnt this by trail and error when I eventually wanted to
add an extra function to what was meant to be a one-function-module
(thankfully I could keep backwards compat via __call).
With a table you can also add other metadata such as a VERSION field.
And you get a few other misc things by being a table, e.g. tracebacks
will be more informative due to how findfield works
https://www.lua.org/source/5.3/lauxlib.c.html#findfield

> 2. Do we locally cache predefined globals?

I used to, but not anymore unless there is a very tight loop: and then
I cache in a local, not an upvalue.
The other time you might see it is for compatability, e.g.
local unpack = table.unpack or unpack

> 3. How do we code sentinel objects (i.e values that like nil are
> guaranteed not to be equal to anything else)?

I have rarely needed this: usually you work around it with e.g. a length field.
However in the rare circumstance: use an empty table: {}

> 4. Do we make big do ... end blocks in our code in order to
> restrict the scope of locals?

Yes, if the initialisation of a local takes up more than one statement

> 5. Do we use some sort of Hungarian notation (i.e. CamelCase,
> quick_brown_fox etc) that advertises what the name will be
> used for)?

No!

> 6. Do we consciously conform to ldoc rules for comments?

No. IMO comments in code should explain why calculations are made in a
specific order, or caution about possibly unexpected side effects:
info that someone browsing the code might not realise at first glance.
Documentation is best kept in a separate file, otherwise you often end
up just re-writing the code implementation in english, rather than
explaining at the higher logical level what the function is for.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
In reply to this post by Hisham
It was thus said that the Great Hisham once stated:

> On 10 June 2017 at 03:02, Sean Conner <[hidden email]> wrote:
> >
> > It was thus said that the Great Dirk Laurie once stated:
> > > 4. Do we make big do ... end blocks in our code in order to
> > > restrict the scope of locals?
> >
> >   I do that quite often.  In fact, I'll do things like:
> >
> >         local somevar do
> >           -- code to do a bunch of stuff
> >           somevar = ...
> >         end
> >
> > to make it clear that there is some non-trivial initialization of a local
> > variable.
>
> Dirk talked about using do-end blocks to restrict the scope of locals,
> but the above example with odd indentation does not do that.

  Took some time, but I found an example that I could give (code that wasn't
written at work):

        local cmdline do
          local C  = lpeg.C
          local P  = lpeg.P
          local SP = P" "
         
          local token = C((P(1) - P" ")^1)
          cmdline = SP^0 * token * (SP * C(P(1)^0))^-1
        end

  -spc (Better?)


Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
In reply to this post by Dirk Laurie-2
On Thu, Jun 8, 2017 at 3:21 PM, Dirk Laurie <[hidden email]> wrote:
> my fingers, choking it down, ever since this thread started, and there
> you go and just casually spit it out.

But I was specifically thinking of brace-placement and the exact
characters needed for indentation, though. The discussion has been
mostly free of that, except semi-humorously.  Once there a multiple
ways to express something, we need style and we need idiom.  And
having this written down is very useful for newcomers.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Dirk Laurie-2
In reply to this post by Sean Conner
2017-06-10 8:51 GMT+02:00 Sean Conner <[hidden email]>:

>         local cmdline do
>           local C  = lpeg.C
>           local P  = lpeg.P
>           local SP = P" "
>
>           local token = C((P(1) - P" ")^1)
>           cmdline = SP^0 * token * (SP * C(P(1)^0))^-1
>         end

Your examples demonstrate what one could call a style idiom:
you are defining and initializing a local value, and enclosing
the code needed for that in a do...end group.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Jorge Eduardo
In reply to this post by Dirk Laurie-2
It was thus that the Great Dirk Laurie once stated:

> A convention for indents
is vital for Python, but  Lua is not Python.

Wow! I liked this quote...
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Andrew Starks-2
In reply to this post by Dirk Laurie-2

On Fri, Jun 9, 2017 at 23:18 Dirk Laurie <[hidden email]> wrote:
2017-06-10 2:10 GMT+02:00 Hisham <[hidden email]>:
> On 8 June 2017 at 10:21, Dirk Laurie <[hidden email]> wrote:
>> 2017-06-08 13:51 GMT+02:00 steve donovan <[hidden email]>:
>>
>>> Heh, but they had curly-braces to deal with, always a fine topic for
>>> bikeshedding!
>>
>> Finally, the word emerges. I have been restraining myself, disciplining
>> my fingers, choking it down, ever since this thread started, and there
>> you go and just casually spit it out.
>
> I've come to dislike this word more and more over the years, as it's
> way too often used as a way to shut down conversations, in the style
> of Godwin's Law. For all the discussions on syntax we've had over the
> years on lua-l, I think this one was one of the best ones, especially
> since (a) it is focused on actual Lua syntax, which has a limited
> scope (and not proposed inventions, for which not even the sky is the
> limit), and (b) it is discussed for what it is: style. Style is
> important, and while it's hard to get good discussions on style that
> go beyond "mine is better than yours", once people get past that point
> one can get some good insights on what makes people's sense of style
> tick, what are their rationales and especially to revisit and
> reevaluate one's own. I learned some good stuff while reading other
> people's style guides and writing my own!

My main beef is that despite the title, there has been almost no
discussion of style (which means: among several ways of doing the
same task, pick one and always do it like that); it's all been about
prettyprinting: how many spaces, what about tabs. why not blank
lines instead, etc. You can no more get people to agree on that
than you can change their taste in music. A convention for indents
is vital for Python, but  Lua is not Python.

Put another way: if all that you are going to achieve is another
program with exactly the same compilable code, it just looks nicer,
fro a certain meaning of 'nice', I don't care what you did, I'm going
to run your code through my in-house reformatter anyway.

Non-trivial style means doing things in a certain way, every time,
so that others on the project (or yourself, next year) feel at home
with the code. Things like:

1. What will our 'require' return? A function? A table? A userdata?
2. Do we locally cache predefined globals?
3. How do we code sentinel objects (i.e values that like nil are
guaranteed not to be equal to anything else)?
4. Do we make big do ... end blocks in our code in order to
restrict the scope of locals?
5. Do we use some sort of Hungarian notation (i.e. CamelCase,
quick_brown_fox etc) that advertises what the name will be
used for)?
6. Do we consciously conform to ldoc rules for comments?

These are some pretty useful questions. I don't mean to bikeshed, but I'd call them Best Practices. I believe style is more about presentation and your list is about convention and practices that, when consistently applied, create a set of reasonable expectations for how things work. 

On style: i can't help but think of books and also the world of ConTeX and LaTeX. Imagine if people argued about what specific font to use or exactly which page layout was best for all projects. It would be nonsense. 

In the world of software developers, we actually argue about whether or not it is better to use a space instead of a tab to indent code. If that is in the realm of debatable topics for software coding style, then it tells me that nobody is really that serious about the topic. 

Little tiny programs and big giant projects will benefit from different styles. Functional programming might benefit from different formatting styles than OOP, and OOP written with tables might be better written in a style that is apart from OOP written with closures. 

At bottom, I enjoy reading code with a thoughtful and consistent formatting style. When someone puts time into how their code looks on the screen, it's easy to spot and fun to follow, especially if Best Practices are followed. 

-Andrew
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
In reply to this post by Dirk Laurie-2
On 06/09/2017 09:18 PM, Dirk Laurie wrote:

> 1. What will our 'require' return? A function? A table? A userdata?

Function if it exports sole function. Table if exports object or
set of functions.

> 2. Do we locally cache predefined globals?

If it is really (at least 1%) improves final performance.
Or if we wish nicer names for globals.

> 3. How do we code sentinel objects (i.e values that like nil are
> guaranteed not to be equal to anything else)?

Usually "{}". But it was noted it is not secure - you may store
sensitive information in that sentinel table. Other way is
"function() end".

> 4. Do we make big do ... end blocks in our code in order to
> restrict the scope of locals?

Yes if it improves code understanding.

> 5. Do we use some sort of Hungarian notation (i.e. CamelCase,
> quick_brown_fox etc) that advertises what the name will be
> used for)?

Almost no. But "is"/"has" prefix for booleans is nice. And plural
names for arrays/tables ("items").

Words concatenation method in variable names is purely
project-dependent choice. Some prefer oneHumpCamelCase, CamelCase,
vanilla_c, of luastyle ("isyieldable").

> 6. Do we consciously conform to ldoc rules for comments?

May not, unless you are Steve Donovan.

-- Martin

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Hisham
On Fri, Jun 9, 2017 at 5:04 PM, Hisham <[hidden email]> wrote:
> Design by voting hardly ever works, especially when there is
> aesthetics involved. Some of these choices are related to each other,
> so a hodgepodge of "most voted options" would likely be inconsistent.

I couldn't agree more. This was just pie in the sky thoughts. I was
thinking from a statistical analysis perspective. I started with yours
on Friday afternoon to see how it works.

https://goo.gl/forms/X3YAfa382ga71Ey62


> Not to mention that lua-l is just a slice of the Lua world as a whole
> (and those who voice their opinions here are a further slice of that),
> so it's hard to represent that as the community opinion too. In any
> case, the styles presented here already display some combinations
> which work well for different people, so I think that's pretty good to
> get people going when defining their own.
>
> -- Hisham
>
> On 9 June 2017 at 15:42, Russell Haley <[hidden email]> wrote:
>> It would be interesting to put these lists of rules that people have
>> generated in a system that records votes and see what the real
>> community opinion of them is. Also, if it collected the list of items
>> you agreed with (and a converse list as well) and then compared that
>> to other peoples lists, you might be able to get a really good picture
>> of peoples various styles.
>>
>> On Thu, Jun 8, 2017 at 3:58 PM, Tim Hill <[hidden email]> wrote:
>>>
>>>> On Jun 6, 2017, at 12:13 AM, steve donovan <[hidden email]> wrote:
>>>>
>>>> On Mon, Jun 5, 2017 at 6:52 PM, Pierre Chapuis <[hidden email]> wrote:
>>>>> [1] https://github.com/Olivine-Labs/lua-style-guide
>>>>
>>>> "Using four spaces or tabs will result in public flogging". Ouch!
>>>>
>>>> Reminds me of when Mike Pall said he would never collaborate with
>>>> anyone who used three-space indents.
>>>>
>>>> Sean has it, I think: there's really not enough rationale for these
>>>> arbitrary things. I would go with Roberto, I don't think he would flog
>>>> anyone for using four spaces.
>>>>
>>>
>>> I’ve used 4 spaces now mostly because my eyesight is poor and it simply helps me see things more clearly. It’s also so common as the default tab for editors that I prefer just going with the flow rather than always fighting other team members and/or other language standards in multi-language projects.
>>>
>>> —Tim
>>>
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
In reply to this post by Martin
On Sun, Jun 11, 2017 at 1:36 PM, Martin <[hidden email]> wrote:
> May not, unless you are Steve Donovan.

Heh. Well to be honest, all the @ soup can be irritating. ldoc also
supports plain doc comments (that start with ---) without needing any
directives. (This is pretty much the style of the Lua standard library
as well)  I think that some care in structured documentation is useful
for external APIs in dynamic languages, because there are no explicit
types.  (In fact, I'm curious about any progress with TypedLua, since
dynamic languages with type annotations are fashionable at the
moment.)

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Charles Heywood
I try to document what types *should* be passed to functions, which means I make heavy use of typed argument and typed return values, but I don't think I brew too much @-soup when programming besides that.

On Sun, Jun 11, 2017, 11:18 steve donovan <[hidden email]> wrote:
On Sun, Jun 11, 2017 at 1:36 PM, Martin <[hidden email]> wrote:
> May not, unless you are Steve Donovan.

Heh. Well to be honest, all the @ soup can be irritating. ldoc also
supports plain doc comments (that start with ---) without needing any
directives. (This is pretty much the style of the Lua standard library
as well)  I think that some care in structured documentation is useful
for external APIs in dynamic languages, because there are no explicit
types.  (In fact, I'm curious about any progress with TypedLua, since
dynamic languages with type annotations are fashionable at the
moment.)

--
--

Software Developer / System Administrator
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
On Sun, Jun 11, 2017 at 7:17 PM, Charles Heywood <[hidden email]> wrote:
> I try to document what types *should* be passed to functions, which means I
> make heavy use of typed argument and typed return values, but I don't think
> I brew too much @-soup when programming besides that.

That's the important part, I think. @usage is often helpful, but
having type in some _structured_ form in the doc comments not only
help the human consumers of the API, but might be used by some
automatic tools as well.  I think this is done by the Lua Eclipse
plugin, but in their wisdom they chose a format which is not quite
ldoc compatible.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Charles Heywood
Wow, totally forgot @usage :P thanks for the quick reply! I use @usage as well for basically every public function, but not for scripts (as instead <script> --help ; auto generates documentation instead! <3)

On Sun, Jun 11, 2017, 12:25 steve donovan <[hidden email]> wrote:
On Sun, Jun 11, 2017 at 7:17 PM, Charles Heywood <[hidden email]> wrote:
> I try to document what types *should* be passed to functions, which means I
> make heavy use of typed argument and typed return values, but I don't think
> I brew too much @-soup when programming besides that.

That's the important part, I think. @usage is often helpful, but
having type in some _structured_ form in the doc comments not only
help the human consumers of the API, but might be used by some
automatic tools as well.  I think this is done by the Lua Eclipse
plugin, but in their wisdom they chose a format which is not quite
ldoc compatible.

--
--

Software Developer / System Administrator
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
In reply to this post by steve donovan
I'd like to find a way to generate the ldoc function headers from the file automagically so I could fill in the details afterwards. 

Russ

Sent from my BlackBerry 10 smartphone on the Virgin Mobile network.
  Original Message  
From: steve donovan
Sent: Sunday, June 11, 2017 9:18 AM
To: Lua mailing list
Reply To: Lua mailing list
Subject: Re: Lua style guide ?

On Sun, Jun 11, 2017 at 1:36 PM, Martin <[hidden email]> wrote:
> May not, unless you are Steve Donovan.

Heh. Well to be honest, all the @ soup can be irritating. ldoc also
supports plain doc comments (that start with ---) without needing any
directives. (This is pretty much the style of the Lua standard library
as well) I think that some care in structured documentation is useful
for external APIs in dynamic languages, because there are no explicit
types. (In fact, I'm curious about any progress with TypedLua, since
dynamic languages with type annotations are fashionable at the
moment.)


Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
It was thus said that the Great Russell Haley once stated:
> I'd like to find a way to generate the ldoc function headers from the file
> automagically so I could fill in the details afterwards. 

  I think it might be relatively easy (I'm saying this without even
bothering to try it) by using something like Luis' ltokenp (but perhaps
something else that preserves comments) to parse Lua code to at least
populate @function, @param, @local, and maybe even @raise (if it sees
error()).

  For example, this function:

        function encode(value,sref,stref)
          local res = ""
       
          if stref and not stref.SEEN then
            res = TAG._stringref(nil,nil,stref)
          end
       
          return res .. __ENCODE_MAP[type(value)](value,sref,stref)
        end

such a tool could return:

        --- Placeholder
        -- @function encode
        -- @param value
        -- @param sref
        -- @param stref
        -- @return
        function encode(value,sref,stref)
        ...

  -spc (I don't understand the full scope of this, so of course it must be
        trivial! 8-P


Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
On 06/11/2017 04:15 PM, Sean Conner wrote:

>   For example, this function:
>
> function encode(value,sref,stref)
>  local res = ""
>
>  if stref and not stref.SEEN then
>    res = TAG._stringref(nil,nil,stref)
>  end
>
>  return res .. __ENCODE_MAP[type(value)](value,sref,stref)
> end
>
> such a tool could return:
>
> --- Placeholder
> -- @function encode
> -- @param value
> -- @param sref
> -- @param stref
> -- @return
> function encode(value,sref,stref)
> ...
>
>   -spc (I don't understand the full scope of this, so of course it must be
> trivial! 8-P

Hmm, as experiment I can create a breed of lua code formatter which
produces output with such autogenerated comments. But is there really
need for this?

Function in Lua may be defined in three ways:

1. "local function <name> (<args>)" //<name> can't contain ":" syntel
2. "function <name> (<args>)"
3. "function (<args>)"

Most obscure case is (3). It is often used as expression for sort() or
gsub(). Do you have a good heuristic how do decide emit/not_emit header
for function, given annotated syntax tree of source?

And by the way, are there good ways to test such formatter? Creating yet
another rock with name like "lcf.experiments" looks like a bad idea.

-- Martin

12345