* lua strings and long comments

[Ron Melby]

a string can be made like this

[[ ........... whole bunch of stuff]] however compiler and zerobrane dont actually treat it as a whole string and comment like things and code descriptions can throw it off.

[=[
]=]

will stop that, and it compiles as string

I have seen
--[[
]]
for long comments and same thing as strings
--[=[
]=]

I have also seen
--[[--
--]]--

until recently, and very much accidentally I found out that the = is important, and not just a style thing yet I cannot find documentation on these are there different modifications of thes operators? where can I find what's what?

[ColeValleyGirl]

I assume you've been following the discussion on the Lua mailing list

The Lua Reference Manual is the obvious starting point. I've linked to 5.1 as you're using FH 6, but it's the same in 5.3.

Programming in Lua has a section on Long Strings which amplifies the information in the Lua Reference Manual (but not in the edition that's free online).

There's probably something in the depths of the Lua Wiki as well but life is too short to try to find it.

[Ron Melby]

Ja, no. been there done that.
I have not been following a discussion on the list.

Literal strings can also be defined using a long format enclosed by long brackets. We define an opening long bracket of level n as an opening square bracket followed by n equal signs followed by another opening square bracket. So, an opening long bracket of level 0 is written as [[, an opening long bracket of level 1 is written as [=[, and so on. A closing long bracket is defined similarly; for instance, a closing long bracket of level 4 is written as ]====]. A long string starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. Literals in this bracketed form can run for several lines, do not interpret any escape sequences, and ignore long brackets of any other level. They can contain anything except a closing bracket of the proper level.

perhaps, if I format it a little differently, it may actually explain something akin to something comprehensible and of useful understanding:

Literal strings can also be defined using a long format enclosed by long brackets.
We define an opening long bracket of level n as an opening square bracket followed by n equal signs followed by another opening square bracket.

So, an opening long bracket of level 0 is written as [[,
an opening long bracket of level 1 is written as [=[, and so on.
A closing long bracket is defined similarly;
for instance, a closing long bracket of level 4 is written as ]====].

A long string starts with an opening long bracket of any level and ends at the first closing long bracket of the same level.
Literals in this bracketed form can run for several lines, do not interpret any escape sequences, and ignore long brackets of any other level.

They can contain anything except a closing bracket of the proper level.

so, reduction to LCD:
So, an opening long bracket of level 0 is written as [[,
A long string starts with an opening long bracket of any level and ends at the first closing long bracket of the same level.
Literals in this bracketed form can run for several lines, do not interpret any escape sequences, and ignore long brackets of any other level.

They can contain anything except a closing bracket of the proper level.
A closing long bracket is defined similarly;

Code: Select all

a =
[[
*
(
)
{
{
"
'
~
#
]
]]

note the 1st closing bracket in the string just before the actual closing brackets, yet this compiles and it runs.

so, we now understand that it ignores ] and finalizes at ]].

now:
A comment starts anywhere with a double hyphen (--) and runs until the end of the line. Lua also offers block comments, which start with --[[ and run until the corresponding ]]. A common trick, when we want to comment out a piece of code, is to write the following:

--[[
print(10) -- no action (comment)
--]]

Now, if we add a single hyphen to the first line, the code is in again:

---[[
print(10) --> 10
--]]

In the first example, the -- in the last line is still inside the block comment. In the second example, the sequence ---[[ does not start a block comment; so, the print is outside comments. In this case, the last line becomes an independent comment, as it starts with --.

ok, hang onto your hat grama, we are headed for the rhubarb!

Code: Select all

--[[  
  varstr:byte([i [, j]])
  varstr:sub(i [, j])
  varstr:find(pattern [, index [, plain]]) 
  varstr:match(pattern [, index])
  varstr:gmatch(pattern)
  varstr:gsub(pattern, replace [, n]) 

  varstr:len() 
  varstr:lower()
  varstr:upper()
  varstr:reverse()
  varstr:rep()
  ]]

oh, dear... when is a comment not a comment? answer, when its a ______ ? string? table? index? error?
now, can I skip level 0, 1, 2, ... and go right to level 256?


these are astoundingly simple examples with astoundingly unhelpful documentation and runtime errors.
but lets say the code is a little more complex and interspersed in some 1, 2, 3... 10 thousand statements.
life is indeed to short.

[ColeValleyGirl]

Lua list discussion starts here.

[tatewise]

Excuse me for dropping in but I think Ron has perhaps not made his problem clear.

In the last code section, he is trying to use the popular technique of commenting out some Lua script.
He is using opening level 0 bracket --[[ and closing level 0 bracket ]]
Unfortunately, the Lua script contains double closing index brackets ]] which prematurely terminate the comment!

A workaround is to use level 1 or higher brackets such as --[==[ and ]==] because ]==] is much less likely to occur in Lua script.
However, such higher level closing brackets may occur when defining long strings or for long comments.
So they may occur in any Lua script that needs to be commented out.
In general, it may not be easy to choose the necessary level of brackets to comment out some script without a search for closing brackets within that section of the script.

[ColeValleyGirl]

In general, it may not be easy to choose the necessary level of brackets to comment out some script without a search for closing brackets within that section of the script.

I agree. The blunderbus solution may be to always use something extreme like --[==========[ but I do wonder why it's necessary to comment out thousands of lines of code. There may be some performance reason why the code can't be restructured, otherwise I personally would be looking at doing that, so that I was commenting out function calls not entire code blocks.

[Mark1834]

Agree - the more fundamental answer is probably to review the code structure. There's no hard and fast rule, but I tend to regard any single function that contains more than a few dozen lines of code as too long - functions should generally do one job and do it well and clearly, otherwise we could be in spaghetti territory.

One possibility for blocking out very large chunks for testing purposes is to surround them with if false then ... end. They're not highlighted as comment lines if you have a context-sensitive editor, but leave plenty of whitespace at either end of the block so it is easy to find again. Don't leave it like that between sessions though, else you will lose track of where you are!

[ColeValleyGirl]

Leaving aside questions of code structure, as I'm sure Ron has reasons for how he structures his code, there is a woeful lack of support out there for anything other than the 'standard' block comment markers.

I can conceive of needing to Toggle Block Comments on quite simple code such as

Code: Select all

x=table1[table2[3]]

Both Lua IDEs that I'm familiar with (I'm not classing the FH plugin editor as an IDE, because I can't conceive of using it for anything other than noddy development -- and mad props to those who persevere to do so) allow you to select a block of code and toggle Block Comment on or off.

However, for my example, both IDEs return --[[ x = table[table2[1]] ]] which is wrong. --[=[ x = table[table2[1]] ]=] is correct.

I believe neither IDE allow you easily to customise the block comment marker (somebody with ZeroBrane should check this -- I no longer have it installed). In ZeroBrane I think you'd need to write a plugin; in VS Code you'd need to write an extension. (Yes, I have been down a rabbit hole this afternoon).

[Mark1834]

I'm not classing the FH plugin editor as an IDE, because I can't conceive of using it for anything other than noddy development

Glad to see you are doing your bit to encourage users to take up the tools that CP provide...

FH is a hobbyist/consumer product (it's probably not even aimed at professional genealogists, never mind retired programmers), so within that context, the FH7 editor is perfectly adequate for learning basic data manipulation skills and is streets ahead of what the competition offers, even if it is "noddy" to you.

[ColeValleyGirl]

FH is a hobbyist/consumer product (it's probably not even aimed at professional genealogists, never mind retired programmers), so within that context, the FH7 editor is perfectly adequate for learning basic data manipulation skills and is streets ahead of what the competition offers, even if it is "noddy" to you.

I agree; maybe 'noddy' was the wrong phrase to use, but it isn't an IDE, only a code editor (and it isn't intended to be anything else).. If you're developing more than one simple plugin, it's useful to have (to mention but a few):

• Code folding
• Cross refencing
• Language documentation links
• Block commenting
• Code formatting
• Syntax checking
• Type checking
• Autocomplete
• Spell checking
• Documentation generation
• Code version control

But people using the FH editor manage without all these, so (again) mad props to them.

[Ron Melby]

re: Mike.
in the situation that failed but compiled in ZB...
I run the plugin and it gives something like line 2. unexpected symbol near '*'.
the compiler must have made it to the second ]] to raise the error. and it is supposed to be a COMMENT anyway, why is the interior being investigated? I could see a ']]' error, or an error that says probably need a higher level '='

re: Helen.
I may not comment out thousands of lines, but some pretty pithy lines in the thousands.
usually however, say I will investigate metatables. so, first thing I do, cuz I still dont get them---
copy the text from the manual in the code, until its near done. I have enough browsers open looking for this and that, clarifying this and that and doing other things. the vagarities of the vague lua documentation being what it is. the stuff I want in docs is hard enough to find anyway, and I can guarantee that I am not chuffed while programming problems, and so inadvertently closing that window for the 100th time when I am trying to reduce all the tabs I have open..... however the second is the usual case and thats why there are [[ ]] probs.

Mark, ditto as written to Helen, additionally; all my programming is in fits and starts, as time finds it, and leaving stuff unremembered is a way of life. I will plug along, things going grand and at some point I want to investigate some niggling error that has been on my mind for months, and so I hit debug on a program and look in the box and there is printing ----- by the way, where is print going when I run a plugin not in debug?

and then there is a matter of style (as if the code) is important.
--++++++++++++++++++++++++++--
------------------------------------------------
- -
-----------------------------------------------

----------------------------------------------- end functions (or others)




****THIS ONE****
--[[--
--]]--
if I add several explicative paragraphs in my head along with reading the manual, ok, I got why it works, but not why you need it.

if there was code inside it, yeah, maybe....

the manual explains part of it, but there are extraneous things in there for no reason other than to confuse.

--[[
--]]
should suffice for code that you are testing to activate by
---[[

I am trying to pick up visual studio, (yet again) but it is hard slogging particlarly without much lua support,

[tatewise]

re: Mike.
in the situation that failed but compiled in ZB...
I run the plugin and it gives something like line 2. unexpected symbol near '*'.
the compiler must have made it to the second ]] to raise the error. and it is supposed to be a COMMENT anyway, why is the interior being investigated? I could see a ']]' error, or an error that says probably need a higher level '='

The FH syntax error actually says 2: unexpected symbol near ')'
The section of code in blue below is the comment string from --[[ to the first level 0 closing bracket ]]
Line 2 has that first closing bracket ]] and the subsequent parenthesis ) is unexpected.
So the interior from --[[ to ]] is not being investigated.

1 --[[
2 varstr:byte([i [, j ]])
3 varstr:sub(i [, j])
4 varstr:find(pattern [, index [, plain]])
5 varstr:match(pattern [, index])
6 varstr:gmatch(pattern)
7 varstr:gsub(pattern, replace [, n])
8 ]]

The FH syntax analysis has no idea what might be contained in comments and simply terminates the comment as soon as the first matching closing bracket is detected. so from its perspective, there is no ']]' error and cannot suggest anything because I suspect it does not look beyond the unexpected symbol.

[ColeValleyGirl]

I may not comment out thousands of lines, but some pretty pithy lines in the thousands.
usually however, say I will investigate metatables. so, first thing I do, cuz I still dont get them---
copy the text from the manual in the code, until its near done. I have enough browsers open looking for this and that, clarifying this and that and doing other things. the vagarities of the vague lua documentation being what it is. the stuff I want in docs is hard enough to find anyway, and I can guarantee that I am not chuffed while programming problems, and so inadvertently closing that window for the 100th time when I am trying to reduce all the tabs I have open..... however the second is the usual case and thats why there are [[ ]] probs.

We all have different programming processes and styles; I'm not going to say anybody else's is wrong, but knowing how they works helps to understand why they're asking for something for which I personally don't see a need.
(However, as I illustrated, --[[ ]] can fail to be interpreted as a long string even around a single line of code).

You may have to resort to creating your block comments manually using --[=[ and ]=].

I am trying to pick up visual studio, (yet again) but it is hard slogging particlarly without much lua support,

I'm not using Visual Studio, which is hard slog, but Visual Studio Code which works very well with Lua if you add the right extensions. (I can recommend the extensions I'm using if it's of interest).

[jayef]

I'm hoping to get into coding LUA (ex Cobol, Fortran, VB) so interested in any tips re IDE, Xtensions etc.

Thanks

[ColeValleyGirl]

I use Visual Studio Code with the Lua Language Server extension (by Sumneko), StyLua for formatting (Lua Langauge Server now has formatting support as well, but I haven't explored it yet), GitLens for GitHub integration.

You can't debug FH plugins in the VS Code environment (at least I haven't worked out how to do it yet).

[Ron Melby]

things giving me fits right now, in that vscode:
do I haul in all the scripts that work together as a workspace?
it does not seem to me that if they exist in the workspace, they are treated as 'protos'....
i.e: (cut to the quick, assume all the junk is there to standalone compile each

QSYS_MAT
function matNAM(iptr)
end
end

pgm:
require 'QSYS_MAT'
name = matNAM(prtINDI
end
it doesnt know what matNAM is.

I am massively refactoring code based on something I learned from mike on a Map Life Facts thread:
and as everyone is aware, I make use of requires without let or hindrance, those requires are divided into functional areas, or so I thought....

so I put luacheck in the extensions (put it in bin actually so I didnt have to change the path)
it sees all the 'warning errors' in the entire library or it is how vscode presents it to luacheck, and I am only concerned with seeing the issues on the cart. (whats active on the editor screen) not whats tabbed, and not the entire library unless I asked for that. and if you go into the messages to see the offending code it creates tabs for the script that the errors are in.

I will not use camel case, nor will I use dunder names in any code I run day in and day out, no way to shut off variable naming, rules or to set ones of my own.

so maybe I am asking is there a clever linter out there that works with vscode and allows at least some configuration?

so, whats a proper workspace? I would assume it is equivalent to project.

[ColeValleyGirl]

Ron,

Try the Lua extension from Sumneko instead of Luacheck. I've got it set to only show me errors in the active tab, and it's never insisted I use camelCase. It's also got tons of config options...

Re: What's a proper workspace?

Note: I don't keep my 'work in progress' in the FH plugins directory, but in a separate directory structure synchronised with Github, so you may need to modify this a bit once you understand the principles.

I use one workspace per plugin, with something like this in the Whatever Plugin.code-workspace file:

Code: Select all

{
  "folders": [
    {
      "path": "D:/OneDrive/Lua Code Repositories/Whatever-Plugin",
      "name": "Whatever Plugin"
    },
    {
      "path": "C:/Program Files (x86)/Family Historian/Program/Lua",
      "name": "Program Files Lua"
    }
  ],
}

The plugin code is in "D:/OneDrive/Lua Code Repositories/Whatever-Plugin".

Including Program/Lua) in the workspace folders path means the Lua extension can use the contents for autosensing without actually including them in the same folder as the plugin code.

You could use the same method for your modules.

[ColeValleyGirl]

You can alternatively include this in the settings.json file for Vscode if you're using the Lua extension:

Code: Select all

    "Lua.workspace.library": [
        "C:\\Program Files (x86)\\Family Historian\\Program\\Lua",
    ],

[ColeValleyGirl]

And if you want to autosense the FH API, include this file in Lua.workspace.library as well, e.g. in settings.json:

Code: Select all

   
 "Lua.workspace.library": [
        "C:\\Program Files (x86)\\Family Historian\\Program\\Lua",
        "D:\\OneDrive\\Lua Code Repositories\\FH API"
 ],
 "Lua.diagnostics.disable": [
       "lowercase-global"
 ],

But note it's for FH7 and you will need to amend it for FH6 (or create one from scratch starting from the list of functions in the FH API help).