[>] [2018-02-23] Sync with main branch.

Author: Ian

get_formatter_ast.lua

@@ -1,13 +1,20 @@
 local get_params = request('get_formatter_ast.get_params')
 local convert = request('!.file.convert')
 local get_ast = request('!.lua.code.get_ast')
-local formatter_preprocess = request('!.formats.lua.save.formatter.preprocess')
+local transform_ast = request('!.formats.lua.transform_ast')
 
 local parse =
   function(s)
     local result
     result = get_ast(s)
-    result = formatter_preprocess(result)
+    result =
+      transform_ast(
+        result,
+        {
+          keep_comments = true,
+          keep_unparsed_tail = true,
+        }
+      )
     return result
   end
 

lcf-scm-1.rockspec

@@ -0,0 +1,135 @@
+# Description
+
+Formats any valid Lua 5.3 code.
+
+Lines with code are wrapped to fit inside given margins.
+
+Files with invalid Lua syntax may lose the content after the syntax
+error! lcf's parser is more permissible than Lua's, so make sure to
+verify the correctness of the file before running lcf.
+For example via `$ luac -p <filename>`.
+
+Installation script deploys three command-line scripts:
+
+  * lua.reformat
+  * lua.get_ast
+  * lua.get_formatter_ast
+
+Last two for people who love tinkering.
+
+
+# Requirements
+
+Sole requirement is Lua v5.3. Earlier versions will not work.
+
+It may or may not work under Windows. I've not tested it there.
+
+For Lua v5.1 checkout `5.1` branch.
+
+
+# Installation
+
+    $ sudo luarocks make lcf-scm-1.rockspec
+
+(also works `$ sudo luarocks install lcf`)
+
+
+# Usage
+
+## From command-line
+
+    $ lua.reformat <f_in>
+
+You can pass formatter parameters in command line. For available
+options call `$ lua.reformat`.
+
+
+## From Lua interpreter
+
+Suppose you have a string with Lua code and wish to get another string
+with formatted code.
+
+    do
+      local lua_code_str = 'do return end' -- < fill it
+
+      require('lcf.workshop.base')
+      local get_ast = request('!.lua.code.get_ast')
+      local get_formatted_code = request('!.formats.lua.save')
+
+      return get_formatted_code(get_ast(lua_code_str))
+    end
+
+
+### Passing formatting parameters
+
+You may override default parameters by passing a table with new values
+of changed parameters:
+
+    get_formatted_code(
+      get_ast(lua_code_str),
+      {
+        indent_chunk = '  ',
+        right_margin = 96,
+        max_text_width = math.huge,
+        keep_unparsed_tail = true,
+        keep_comments = true,
+      }
+    )
+
+* `indent_chunk` is a string using for building one indent. You may try
+  value `|..` to see it's effect.
+
+* `right_margin` limits length of line with indent. Setting it makes
+  sense for printing.
+
+* `max_text_width` limits length of line without indent, i.e. length of
+  text in line. Setting it makes sense for windowed viewing in editor.
+
+* `keep_unparsed_tail` is a flag to keep text after point where we
+  failed to parse source.
+
+  Syntactically incorrect code may lose significant parts even with
+  this flag. For example `f() = a` is formatted as `f()`. (Because
+  it's parsed as assignment but formatted as function call.) But text
+  like `1; f() = a` will fail to parse and will remain intact.
+
+* `keep_comments` is a flag to keep comments. Comment text is not changed
+so comments may last beyond right margin.
+
+  Comments are "sinked-up" to statements level. So text
+
+      function(a, --parameter "a"
+        b) --parameter "b"
+      end
+
+  is formatted as
+
+      --parameter "a"
+      function(a, b)
+        --parameter "b"
+      end
+
+  This is done to keep formatting routines simple.
+
+---
+
+* Based on my own generic stream processing core,
+  which is extended to generic strings parser,
+  which uses my own loseless Lua syntax representation,
+  produces AST (annotated syntax tree),
+  which is further simplified and structured for code formatter,
+  which produces code layout,
+  trying all possible variants to fit code under given margins
+  and maintain indentation.
+
+* It uses local copy of my ["workshop"](https://github.com/martin-eden/workshop) code hive.
+
+* See also [my repositories contents](https://github.com/martin-eden/contents).
+
+---
+```
+2016-08-16
+2017-01-28
+2017-09-26
+2018-02-23
+```

readme.md

@@ -1,6 +1,6 @@
 local get_params = request('reformat.get_params')
 local get_ast = request('!.lua.code.get_ast')
-local serialize_ast = request('!.formats.lua.save')
+local serialize_ast = request('!.lua.code.ast_as_code')
 local convert = request('!.file.convert')
 
 return

readme.txt

@@ -14,22 +14,24 @@ cmdline_processor.allowed_params =
   {
     {name = 'f_in_name', type = 'string'},
     {name = 'f_out_name', type = 'string'},
+    {name = 'indent', type = 'key_str'},
     {name = 'right-margin', type = 'key_int'},
     {name = 'max-text-width', type = 'key_int'},
     {name = 'keep-comments', type = 'flag'},
-    {name = 'indent', type = 'key_str'},
+    {name = 'keep-unparsed-tail', type = 'flag'},
   }
 
 --[[
   Although original default parameters are stored in
-  [lua.save.formatter.interface] I override it here.
+  [lua.formatter.interface] I override it here.
 ]]
 local default_formatter_options =
   {
-    right_margin = 120,
-    max_text_width = 100,
     indent_chunk = '  ',
+    right_margin = 96,
+    max_text_width = math.huge,
     keep_comments = true,
+    keep_unparsed_tail = true,
   }
 
 local table_to_str = request('!.formats.lua_table.save')
@@ -39,23 +41,24 @@ return
     assert_table(args)
     if not args[1] or (args[1] == '--help') then
       print(usage_text)
-      print('Default options:')
+      print('Defaults:')
       print(table_to_str(default_formatter_options))
+      print('\n-- Martin, 2018-02')
       return
     end
 
     local params = cmdline_processor:run(args)
 
-    local f_in_name, f_out_name
-    f_in_name = params.f_in_name
+    local f_in_name = params.f_in_name
     if not f_in_name then
       print(usage_text)
       return
     end
-    f_out_name = params.f_out_name or (f_in_name .. '.formatted')
 
-    params['max-text-width'] = params['max-text-width'] or params['right-margin']
-    params['right-margin'] = params['right-margin'] or params['max-text-width']
+    local f_out_name = params.f_out_name
+    if not f_out_name then
+      f_out_name = f_in_name .. '.formatted'
+    end
 
     local formatter_options =
       new(
@@ -65,6 +68,7 @@ return
           right_margin = params['right-margin'],
           max_text_width = params['max-text-width'],
           keep_comments = params['keep-comments'],
+          keep_unparsed_tail = params['keep-unparsed-tail'],
         }
       )
 

reformat.lua

@@ -3,24 +3,24 @@ return
 Reformat Lua 5.3 code.
 
 lua.reformat   <f_in>   [<f_out>]
-             ^        ^           ^
-             |        |           |
-             +-- [<options>] -----+
+             ┬        ┬           ┬
+             │        │           │
+             └── [<options>] ─────┘
 
 <options>:
-  --right-margin=<int> -- Right margin, indent chars counts.
-  --max-text-width=<int> -- Maximum text length, ignoring indent chars.
-  --keep-comments -- Keep comments.
-  --~keep-comments -- Remove comments.
-  --indent=<str> -- Use given string as indent chunk
 
-Notes
-  * In case when only one parameter of (right-margin, max-text-width)
-    is given, another parameter is set to same value. This is done
-    because these parameters have similar effect and in other case
-    you wish to set another parameter to near value manually.
+  --indent=<str>          Use given string as indent chunk.
 
-  * If <f_out> name is not given, it's generated using <f_in> name.
+  --right-margin=<int>    Right margin, including indent part.
+  --max-text-width=<int>  Maximum text length, excluding indent part.
 
--- Martin, 2017-10-14
+  --keep-comments         Keep comments.
+  --~keep-comments        Remove comments.
+
+  --keep-unparsed-tail    Keep unparsed file end.
+  --~keep-unparsed-tail   Remove unparsed file end.
+
+<f_out>:
+
+  If not given, file name is generated using <f_in> prefix.
 ]]