Module mc

High-level Midnight Commander services.

Applications

activate(path[, action]) “Opens” a document.
diff(path1, path2) Launches the diff-viewer.
edit(path[, line[, internal]]) Launches the editor.
help([help_id[, help_file]]) Launches the help viewer.
view(path[, line[, internal[, raw]]]) Launches the viewer.
view_command(command[, line]) Launches the viewer to view the output of a command.

Shell

execute(s) Executes a command as if typed at the prompt.
expand_format(s, [editbox], [dont_quote]) Expands a format string.
name_quote(s, [quote_percent]) Quotes a filename to be used by the shell.

Misc

is_background() Whether we're a background process.
is_standalone() Whether we're running in standalone mode.

File operations

cp(src, dst[, opts]) Copies files.
cp_i(src, dst[, opts]) Copies files, interactively.
mv(src, dst[, opts]) Moves (or renames) files.
mv_i(src, dst[, opts]) Moves (or renames) files, interactively.
rm(files[, opts]) Deletes files.
rm_i(files[, opts]) Deletes files, interactively.


Applications

activate(path[, action])
“Opens” a document. 

-- View a picture. (Note that the file is inside an archive, and
-- there's no problem in that.)
mc.activate("/media/web/pictures.rar/urar://london/big ben.jpg")

The short description:

Normally, when you hit Enter while standing on a document (e.g., a picture, video file, etc.), MC “opens” it by launching the associated application. That’s what this function does.

The long description:

MC has an “extension file”, which is a database that describes how to carry out actions —notably “Open”, “View” and “Edit”— on a file. What this function does is carry out the actions described in that database. By default it carries out the “Open” action, but by supplying the action parameter you can carry out any other action.

There’s a convention in the extension file to capitalize action names. So make sure to type “Edit”, not “edit”. But if it’s editing or viewing you're after, simply use mc.edit or mc.view.

Returns:

The string “ok”, “missing”, or “error”.

diff(path1, path2)
Launches the diff-viewer.
edit(path[, line[, internal]])

Launches the editor.

Example:

mc.edit('/etc/issue')

Parameters:

  • path
  • line — Start with the cursor positioned on this line. Leave empty (or zero) to load saved position. (optional)
  • internal — Boolean. Whether to force using the internal editor. Leave empty for user preference. (optional)
help([help_id[, help_file]])
Launches the help viewer.

Parameters:

  • help_id The name of the section to display. Leave empty for the main section. (optional)
  • help_file The path to the help file. Leave empty for the builtin help file. (optional)
view(path[, line[, internal[, raw]]])
Launches the viewer.

Parameters:

  • path
  • line — Scroll to this line. Leave empty (or zero) to load saved position. (optional)
  • internal — Boolean. Whether to force using the internal viewer. Leave empty for user preference. (optional)
  • raw — Boolean. If set, does not do any fancy pre-processing (no filtering). Implies “internal”. (optional)
view_command(command[, line])

Launches the viewer to view the output of a command. 

mc.view_command("ls -la")

Another example:

-- Execute the command-line "into" the viewer. Can be useful.
ui.Input.bind("f17", function(ipt)
  mc.view_command(ipt.text)
end)

Shell

execute(s)
Executes a command as if typed at the prompt. 

mc.execute("ls -la")

If you aren’t interested in the visual implications of this function, or if you wish to process the output of the command, then you should use os.execute or io.popen instead.

You can use this function even when the prompt isn’t visible; e.g., inside the editor or the viewer. The user is always able to press C-o to see the command’s output.

If the panel displays a directory of a non-local filesystem, the shell’s “current directory” will be a different one, of course. If you want to guard against this, do:

if fs.current_vdir():is_local() then
  mc.execute("ls -l")
else
  alert(T"Cannot execute commands on non-local filesystems")
end

If you do want to execute a shell command on a file on a non-local filesystem, do that with the help of fs.getlocalcopy.

Percent-tokens (e.g. “%d/%f”) aren’t recognized. Use expand_format if you need these.

expand_format(s, [editbox], [dont_quote])
Expands a format string.

A “format string” is a text with some embedded percent-tokens in it.

ui.Panel.bind("f16", function(pnl)
  mc.execute(mc.expand_format("echo You are standing on %f"))
end)

ui.Editbox.bind("f16", function(edt)
  alert(mc.expand_format("You're editing a file of type %y.", edt, true))
end)

For a list of the available tokens, see src/filemanager/usermenu.c:expand_format().

While this function seems useful, there’s not much reason to use it as you have the power of a programming language and can access a panel’s (and editbox') properties directly.

name_quote(s, [quote_percent])

Quotes a filename to be used by the shell.

This is like utils.text.shell_quote, with the following differences which make it more suitable for quoting filenames to be used on the command line:

  • If the string begins with “–”, the function precedes it with “./” (so that it won’t be mistaken, by the program you'll be handing it to, for an option name).

  • If the quote_percent flag is true, replaces “%” with “%%” (as this char, undoubled, is processed by MC’s command line).

Example:

-- Inserts the currently selected filename into the command line.

ui.Panel.bind('C-enter', function(pnl)
  local ipt = ui.current_widget('Input')
  if ipt then  -- it may be toggled off.
    ipt:insert( mc.name_quote(pnl.current) .. ' ' )
  end
end)

Misc

is_background()
Whether we're a background process.

MC is capable of copying and moving files in the background: it forks and does the I/O in a separate process. This is of no consequence to a Lua programmer except when one’s writing a filesystem: you cannot use the UI in a background process, except for a few facilities marked explicitly as “safe” on the prompts page. E.g., you can use prompts.get_password to read a password but you cannot generally construct more complex dialogs.

is_standalone()
Whether we're running in standalone mode.

That is, whether we're running via the ‘mcscript’ binary (or using the --script or -L switches).

In this mode MC runs a Lua script and then exits.

See the user guide.

File operations

The following functions let you copy/move/delete files (and directories — we don’t distinguish between the two here). They deal with whole files (in contrast to the low level API of the fs module.)

Specifying files: Each of the arguments src, dst, and files may be either a single filepath or a list of such. Example:

cp('one.txt', 'two.txt')
cp({'one.txt', 'two.txt'}, 'dir')

You can also do:

cp({'one.txt', 'two.txt'}, {'one.md', 'two.md'})

which is like doing:

cp('one.txt', 'one.md')
cp('two.txt', 'two.md')

But the former is better because it uses one context. If the user is asked about overwriting a file and chooses “All”, his choice will be remembered for the second file as well. On the other hand, when using two separate cp() calls, two unrelated contexts are used.

The optional opts argument is a table of options. For example:

  • deref – Whether to dereference symbolic links.
  • BUFSIZ – The buffer size for reading/writing. The default is 1MB.

This table is in fact merged into the context object.

cp(src, dst[, opts])

Copies files.

A simple example:

mc.cp(tglob('/etc/*.conf'), '.')

Another example:

-- Download all *.pdf files from a remote server to the current
-- directory, but only files that are newer than what we already
-- have.

mc.cp(
  fs.tglob('sh://john@example.com/vhosts/john/public_html/tmp/*.pdf'),
  '.',
  {
    decide_on_overwrite = function (src, dst)
      return "update"
    end,
  }
)

-- UPDATE: MC seems to have a bug when handling dates over
--         'sh://': the date will be "translated" over the
--         timezone. So the "update" trick above won't work
--         as expected :-(
cp_i(src, dst[, opts])
Copies files, interactively.

If the destination already exists, the user will be asked if he wants to overwrite it, etc. So in the case of other scenarios demanding a decision.

the i in the function name comes from the shell command cp -i.

If the UI isn’t ready (and hence questions can’t be posed to the user), this function behaves like cp.

mv(src, dst[, opts])
Moves (or renames) files.
mv_i(src, dst[, opts])
Moves (or renames) files, interactively.

For the meaning of “interactively”, see in cp_i.

rm(files[, opts])
Deletes files.
rm_i(files[, opts])
Deletes files, interactively.
generated by LDoc 1.4.3 Last updated 2016-08-25 13:39:01