FarNet.FSharpFar
4.0.1
Prefix Reserved
See the version list below for details.
dotnet add package FarNet.FSharpFar --version 4.0.1
NuGet\Install-Package FarNet.FSharpFar -Version 4.0.1
<PackageReference Include="FarNet.FSharpFar" Version="4.0.1" />
paket add FarNet.FSharpFar --version 4.0.1
#r "nuget: FarNet.FSharpFar, 4.0.1"
// Install FarNet.FSharpFar as a Cake Addin #addin nuget:?package=FarNet.FSharpFar&version=4.0.1 // Install FarNet.FSharpFar as a Cake Tool #tool nuget:?package=FarNet.FSharpFar&version=4.0.1
FarNet.FSharpFar
F# scripting and interactive services in Far Manager
- Menus
- Commands
- Configuration
- Projects
- Debugging
- Interactive
- Editor services
- Using F# scripts
- Using fsx.exe tool
- FSharpFar packages
Project
- Source: FarNet/FSharpFar
- Author: Roman Kuzmin
Credits
- FSharpFar is based on FSharp.Compiler.Service.
Installation
- Far Manager
- Package FarNet
- Package FarNet.FSharpFar
How to install and update FarNet and modules:
https://github.com/nightroman/FarNet#readme
As a result, you get the complete F# scripting portable with Far Manager.
Use it with Far Manager by FSharpFar or without Far Manager by fsx.exe.
Menus
Use [F11]
\ FSharpFar
to open the module menu:
Interactive
Opens the default session interactive.
Sessions...
Shows the list of opened sessions. Keys:
[Enter]
Opens the session interactive.
[Del]
Closes the session and interactives.
[F4]
Edits the session configuration file.
Load
Evaluates the script opened in editor (
#load
).Tips
Shows help tips for the symbol at the caret.
Check
Checks the current F# file for errors.
Errors
Shows the errors of the last check.
Uses in file
Shows uses of the symbol in the file as a go to menu.
Uses in project
Shows uses of the symbol in the project in a new editor.
Enable|Disable auto tips
Toggles auto tips on mouse moves over symbols.
Enable|Disable auto checks
Toggles auto checks for errors on changes in the editor.
Commands
The command prefix is fs:
. It evaluates F# expressions and directives with
the specified or default session and runs special commands.
F# expressions:
fs: FarNet.Far.Api.Message "Hello"
fs: System.Math.PI / 3.
F# directives:
fs: #load @"C:\Scripts\FSharp\Script1.fsx"
fs: #time "on"
fs: #help
open
fs: open: with = <config>
with
(optional) configuration file
The open
command opens the interactive editor with the specified or default configuration.
Sample file association:
A file mask or several file masks:
*.fs.ini
Description of the association:
F# interactive
─────────────────────────────────────
[x] Execute command (used for Enter):
fs: open: with="!\!.!"
exec
fs: exec: <parameters>
fs: exec: <parameters> ;; <code>
Parameters:
file = <script> ; with = <config>
file
(optional) F# script filewith
(optional) configuration file
The exec
command invokes a script or F# code with the specified or default configuration.
The default is *.fs.ini
in the script folder or the active panel.
If there is none then the main configuration is used.
Examples:
fs: exec: file = Script1.fsx
fs: exec: file = Module1.fs ;; Module1.test "answer" 42
fs: exec: with = %TryPanelFSharp%\TryPanelFSharp.fs.ini ;; TryPanelFSharp.run ()
The first two commands evaluate the specified files on every call. The last
command loads files specified by the configuration once, then it just runs
the code after ;;
.
Sample file association:
A file mask or several file masks:
*.fsx;*.fs
Description of the association:
F# script
─────────────────────────────────────
[x] Execute command (used for Enter):
fs: exec: file="!\!.!"
[x] Execute command (used for Ctrl+PgDn):
fs: #load @"!\!.!"
compile
fs: compile: with = <config>
with
(optional) configuration file
Compiles a library (dll) with the specified or default configuration.
The default is *.fs.ini
in the active panel.
The command is used for making FarNet scripts or modules without installing anything else. But it may create any .NET libraries, not just for FarNet.
Configuration notes:
- At least one source file must be specified.
- The section
[out]
may specify{-o|--out}:<file.dll>
but if it is omitted then the FarNet script is assumed with its name derived from configuration or its folder.
project
fs: project: open = VS|VSCode; type = Normal|Script; with = <config>
Generates and opens F# project from the specified or default configuration.
The default is *.fs.ini
in the active panel.
Parameters:
open
(optional) tells how to open the project:VS
(default) for Visual StudioVSCode
for Visual Studio Code
type
(optional) specifies the project type:Normal
(default) for the default output or specified by[out]
Script
for%FARHOME%\FarNet\Scripts\<name>\<name>.dll
with
(optional) specifies the configuration file.
See also: Projects
Configuration
Each interactive session is associated with its configuration file path. If the
configuration is not specified then the default is used. The default is first
*.fs.ini
in the active panel, in alphabetical order. If there is none then
the main configuration is used: %FARPROFILE%\FarNet\FSharpFar\main.fs.ini.
Source file services use configuration files in source directories. If they are not found then the main configuration is used.
In commands with configurations (fs: //... with=...
)
you may specify configuration directory instead of file.
If you change configurations in Far Manager editors then affected sessions are closed automatically.
If you change them externally then you may need to reset affected sessions manually.
The configuration file format is similar to INI, with sections and options.
Empty lines and lines staring with ;
are ignored.
Available sections
[fsc]
This is the main section. It defines F# Compiler Options and source files. This section is often enough. Other sections may add extra or override defined options.
The specified paths may be absolute and relative with environment %variables% expanded.
Important: relative paths for -r|--reference
must start with dot(s) (".\
" or "..\
"),
otherwise they are treated as known assembly names like -r:System.ComponentModel.Composition
.
; Main section
[fsc]
--warn:4
--optimize-
--debug:full
--define:DEBUG
-r:%MyLib%\Lib1.dll
-r:..\packages\Lib2.dll
-r:System.ComponentModel.Composition
File1.fs
File2.fs
[out]
This section defines sources and options for fs: compile:
, and fs: project:
.
The output target {-o|--out}:<file.dll>
is respected by fs: compile:
and
fs: project: type=Normal
. If it is missing then the FarNet script target
location is assumed with the script name derived either from the
configuration file or its directory.
Example: TryPanelFSharp - how to make FarNet modules from sources.
; Build FarNet module TryPanelFSharp
[out]
Module.fs
-o:%FARHOME%\FarNet\Modules\TryPanelFSharp\TryPanelFSharp.dll
Options -a
and --target
are ignored, --target:library
is always used.
[use]
This section tells to include other configuration files, one per line, using relative or absolute paths. Thus, the current session may be easily composed from existing "projects" with some additional settings and files.
; Use the main configuration in this configuration
[use]
%FARPROFILE%\FarNet\FSharpFar\main.fs.ini
[fsi]
This section defines F# Interactive Options and source files used for interactive sessions and evaluating scripts.
--use
files are particularly useful for interactive commands. They normally
open frequently used namespaces and modules and define some helper functions
and variables.
; My predefined stuff for interactive
[fsi]
--use:Interactive.fsx
[etc]
This section defines options for "Editor Tips and Checks", hence the name.
It is useful in some cases, e.g. --define:DEBUG
is used in [etc]
for
tips and checks in #if DEBUG
code blocks.
Preprocessing
The specified paths are preprocessed as follows:
- Environment variables specified as
%VARIABLE%
are expanded to their values. - The variable
%$Version%
is replaced with common language runtime version. __SOURCE_DIRECTORY__
is replaced with the configuration file directory.- Not rooted paths are treated as relative to the configuration directory.
Predefined
Some F# compiler settings are predefined:
--lib
: %FARHOME%--reference
: FarNet.dll, FarNet.FSharp.dll, FSharpFar.dll
The compiler symbol FARNET
is defined on using with FSharpFar.
It is not defined in other cases, for example with fsx.exe.
Use #if FARNET
or #if !FARNET
for conditional compilation:
#if FARNET
// code for FSharpFar and FarNet
#else
// code for fsx.exe or fsi.exe
#endif
Troubleshooting
Mistakes in configurations cause session loading errors, often without much useful information. Check your configuration files:
- All the specified paths should be resolved to existing targets.
- Relative
-r|--reference
paths must start with.\
or..\
. - Interactive options are specified in
[fsi]
, not in[fsc]
. - Output options are specified in
[out]
, not in[fsc]
.
F# scripts and configurations
- Scripts, i.e.
*.fsx
files, should not be added to configurations, except--use
in[fsi]
. - Scripts may use
#I
,#r
,#load
directives instead of or in addition to configurations. - Configurations understand environment variables, script directives do not.
- Configurations may specify compiler options, scripts cannot do this.
Session source and use-files
Source and use-files (--use
) are used in order to load the session for checks and interactive work.
Use-files are invoked in the session as if they are typed interactively. The goal is to prepare the session for interactive work and reduce typing, i.e. open modules and namespaces, define some functions and values, etc.
Sample use-file:
// reference assemblies
#r "MyLib.dll"
// namespaces and modules
open FarNet
open System
// definitions for interactive
let show text = far.Message text
Projects
With a configuration file *.fs.ini
, use the following command in order to
generate *.fsproj
with the source files and open it by the associated program
(usually Visual Studio) or by VSCode:
fs: project: open=VS|VSCode; type=Normal|Script; with=<config>
VSCode should have installed the F# extension.
If type=Normal
and the configuration specifies the output section, the
generated project is configured accordingly. This may be used for building,
running, and debugging FarNet modules from sources.
Example: TryPanelFSharp - how to make FarNet modules from sources.
If type=Script
the output is %FARHOME%\FarNet\Scripts\<name>\<name>.dll
where <name>
is inferred from the configuration or its folder.
Without the configured output generated projects are still useful for working with sources in a more powerful IDE. You may build to make sure everything is correct but normally code checkers show errors quite well without building. Edit sources, save, switch to Far Manager (no restart needed), and invoke.
Generated projects include:
- References to FarNet and FSharpFar assemblies.
- References to assemblies in the
[fsc]
section. *.fs
source files in[fsc]
and[out]
.- Other
*.fs
files in the current panel. *.fsx
scripts in the current panel.
Generated projects are %TEMP%\_Project_X\Y.fsproj
where X and Y are based on
the configuration file and its parent directory names.
Associate .fsproj with Visual Studio 2022
On problems with associating .fsproj files with Visual Studio 2022, use this registry tweak:
HKEY_CLASSES_ROOT\fsproj_auto_file\shell\open\command
"C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\devenv.exe" "%1"
Debugging
Direct script debugging is not possible because FSharp.Compiler.Service 38.0+ does not support this
For debugging, use temporary FarNet scripts or modules, see Projects.
Consider developing complex code as FarNet scripts and debug when needed. Then reference script assemblies and call their methods from F# scripts.
Interactive
F# interactive is the editor session for evaluating one or more lines of code.
Use [ShiftEnter]
for evaluating and [Tab]
for code completion. The output
of evaluated code is appended to the end with the text markers (*(
and )*)
.
The structure of interactive text in the editor:
< old F# code, use [ShiftEnter] to add it to new >
(*(
<standard output and error text from code, i.e. from printf, eprintf>
<output text from evaluator, i.e. loading info, types, and values>
<error stream text from evaluator>
<errors and warnings>
<exceptions>
)*)
< new F# code, use [ShiftEnter] to evaluate >
< end of file, next (*( output )*) >
Use [F5]
to show the interactive history.
The history list keys:
[Enter]
- append code to the interactive.[Del]
,[CtrlR]
- tidy up the history.- Other keys are for incremental filtering.
Note, interactive sessions are closed automatically when you edit and save configuration and source files in the same Far Manager or projects opened by "Project" from the same Far Manager. On editing files externally you may need to reset affected sessions manually.
Editor services
Editor services are automatically available for F# files opened in editors. If
files are not self-contained then use the configuration file *.fs.ini
in the
same directory. Specify source files and references, normally in [fsc]
.
Code completion
Use [Tab]
in order to complete code.
Source completion is based on the current file content and the configuration.
Interactive completion is based on the current session and its configuration.
Code evaluation
Use [F5]
or [F11]
\ FSharpFar
\ Load
in order to evaluate the file.
The file is automatically saved before loading.
The output is shown in a new editor.
Type info tips
Use [F11]
\ FSharpFar
\ Tips
in order to get type tips for the symbol at the caret.
Use [F11]
\ FSharpFar
\ Enable|Disable auto tips
in order to toggle auto tips on mouse moves over symbols.
Code issues
Use [F11]
\ FSharpFar
\ Check
in order to check the file for syntax and type errors.
Use [F11]
\ FSharpFar
\ Errors
in order to show the menu with the last check errors.
Use [F11]
\ FSharpFar
\ Enable|Disable auto checks
in order to toggle auto checks on typing.
Found errors and warnings are highlighted in the editor and kept until the editor text changes. Error messages are automatically shown when the mouse hovers over highlighted error areas.
To change highlighting colors, edit module settings:
[F11]
\ FarNet
\ Settings
\ FSharpFar\Settings
.
Symbol uses
Use [F11]
\ FSharpFar
\ Uses in file
and Uses in project
in order to
get definitions and references of the symbol at the caret. Same file uses are
shown as a go to menu. Project uses are shown in a new editor.
Using F# scripts
(See /samples for some example scripts.)
How to run F# script tools in Far Manager?
Running as commands
fs: exec: [file = <script>] [; with = <config>] [;; F# code]
Commands in Far Manager may be invoked is several ways:
- Typed in the panels command line.
- Typed in the "Invoke" input box.
- Stored in user menus.
- Stored in file associations.
- Invoked by macros bound to keys.
The first two option are available right away. In panels type commands in the
command line. In other areas use the menu F11
\ FarNet
\ Invoke
to open
the command input box.
Other ways need some work for defining and storing commands. But then commands are invoked without typing.
F# scripts in user menus
fs:
commands are easily added, edited, and called from the user menus.
By design, the user menu is available just in panels and opened by [F2]
.
NOTE: The main or custom user menus can be opened in other areas by macros
using mf.usermenu
. For the details about macros see Far Manager manuals.
F# scripts in file associations
Associate commands running F# scripts with their file extensions or more complex masks.
Use F9
\ Commands
\ File associations
, for example:
A file mask or several file masks:
*.fsx;*.fs
Description of the association:
F# Far script
─────────────────────────────────────
[x] Execute command (used for Enter):
fs: exec: file="!\!.!"
[x] Execute command (used for Ctrl+PgDn):
fs: #load @"!\!.!"
F# scripts assigned to keys
F# scripts may be assigned to keys using Far Manager macros. Example:
Macro {
area="Common"; key="CtrlShiftF9"; description="F# MyScript";
action=function()
Plugin.Call("10435532-9BB3-487B-A045-B0E6ECAAB6BC", [[fs: exec: file=C:\Scripts\Far\MyScript.fsx]])
end;
}
Using fsx.exe tool
The included fsx.exe
may be used for running
scripts or interactive sessions without Far Manager.
fsx.exe
does not depend on FarNet, FSharpFar, and Far Manager.
It just uses F# services installed with FSharpFar.
Comparing to the official F# interactive, fsx.exe
supports *.fs.ini
configurations and includes minor interactive improvements.
Usage
fsx.exe [*.ini] [options] [script [arguments]]
If the first argument is like *.ini
then it is treated as the configuration
file for F# compiler options, references, and sources from the [fsc]
section.
Other arguments are F# Interactive Options.
If the configuration is omitted then fsx.exe
looks for *.fs.ini
in the last
specified source file directory, or the current directory for a command without
sources.
Script environment and arguments
The environment variable %FARHOME%
is set to the fsx.exe
directory.
This variable may be used in configuration files for items "portable with Far Manager".
Script arguments specified in the command line are available as the array
fsi.CommandLineArgs
. The first item is the script name, others are script
arguments.
Note that if a script is invoked in FSharpFar then arguments are not used.
fsi.CommandLineArgs
is available but it contains just a dummy string.
Conditional compilation may be used for separating FarNet code from exclusively
designed for fsx
or fsi
. Use #if FARNET
or #if !FARNET
directives.
See /samples/fsx-sample.
FSharpFar packages
These packages are libraries for F# scripting using FSharpFar and fsx.
They are installed in the same way as FarNet modules but they are different.
The directory is %FARHOME%\FarNet\Lib
instead of %FARHOME%\FarNet\Modules
.
Once installed, the content of such packages is portable with Far Manager.
Each package has its *.ini
file for use in other F# configuration files.
-
FarNet friendly FSharp.Charting extension, see /samples.
The alternative package: FarNet.ScottPlot. It is suitable for all modules (C#, F#) and scripts (F#, PowerShell, JavaScript).
-
FSharp.Data package for FarNet.FSharpFar see /samples.
-
F# friendly PowerShell extension, see /samples.
-
Easy and handy assert expressions for tests, see /samples.
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
5.0.2 | 52 | 12/21/2024 |
5.0.1 | 52 | 12/18/2024 |
5.0.0 | 100 | 11/30/2024 |
4.1.0 | 108 | 11/16/2024 |
4.0.1 | 332 | 2/29/2024 |
4.0.0 | 341 | 11/19/2023 |
3.1.1 | 424 | 10/25/2023 |
3.1.0 | 361 | 10/13/2023 |
3.0.1 | 650 | 1/1/2023 |
3.0.0 | 478 | 11/18/2022 |
2.0.14 | 492 | 11/4/2022 |
2.0.13 | 493 | 11/1/2022 |
2.0.12 | 492 | 10/7/2022 |
2.0.11 | 489 | 10/5/2022 |
2.0.10 | 566 | 9/19/2022 |
2.0.9 | 509 | 9/4/2022 |
2.0.8 | 566 | 8/27/2022 |
2.0.7 | 569 | 8/25/2022 |
2.0.6 | 573 | 8/22/2022 |
2.0.5 | 506 | 8/18/2022 |
2.0.4 | 589 | 7/31/2022 |
2.0.3 | 592 | 7/31/2022 |
2.0.2 | 602 | 7/27/2022 |
2.0.1 | 566 | 7/26/2022 |
2.0.0 | 532 | 7/19/2022 |
1.17.2 | 593 | 5/12/2022 |
1.17.1 | 624 | 3/9/2022 |
1.17.0 | 1,092 | 12/3/2021 |
1.16.3 | 2,877 | 11/25/2021 |
1.16.2 | 425 | 11/17/2021 |
1.16.1 | 429 | 11/11/2021 |
1.16.0 | 479 | 11/4/2021 |
1.15.1 | 543 | 7/28/2021 |
1.15.0 | 535 | 2/11/2021 |
1.14.0 | 547 | 1/1/2021 |
1.13.6 | 554 | 12/26/2020 |
1.13.5 | 543 | 12/24/2020 |
1.13.4 | 612 | 12/21/2020 |
1.13.3 | 601 | 11/27/2020 |
1.13.1 | 580 | 10/28/2020 |
1.13.0 | 555 | 10/26/2020 |
1.12.0 | 620 | 7/28/2020 |
1.11.4 | 601 | 7/24/2020 |
1.11.3 | 537 | 7/21/2020 |
1.11.2 | 593 | 7/15/2020 |
1.11.1 | 725 | 7/11/2020 |
1.11.0 | 592 | 7/10/2020 |
1.10.8 | 611 | 7/3/2020 |
1.10.7 | 608 | 6/29/2020 |
1.10.6 | 644 | 6/24/2020 |
1.10.5 | 701 | 6/22/2020 |
1.10.4 | 575 | 6/18/2020 |
1.10.3 | 683 | 6/14/2020 |
1.10.2 | 654 | 6/9/2020 |
1.10.1 | 607 | 6/8/2020 |
1.10.0 | 622 | 6/5/2020 |
1.9.21 | 633 | 6/1/2020 |
1.9.20 | 669 | 5/29/2020 |
1.9.19 | 648 | 5/13/2020 |
1.9.18 | 651 | 3/17/2020 |
1.9.17 | 622 | 3/5/2020 |
1.9.16 | 767 | 2/24/2020 |
1.9.15 | 655 | 2/6/2020 |
1.9.14 | 738 | 1/29/2020 |
1.9.13 | 650 | 1/23/2020 |
1.9.12 | 703 | 12/10/2019 |
1.9.11 | 632 | 11/9/2019 |
1.9.10 | 645 | 10/1/2019 |
1.9.9 | 741 | 8/13/2019 |
1.9.8 | 692 | 8/9/2019 |
1.9.7 | 693 | 7/2/2019 |
1.9.6 | 766 | 5/28/2019 |
1.9.5 | 797 | 3/31/2019 |
1.9.4 | 714 | 2/28/2019 |
1.9.3 | 744 | 2/21/2019 |
1.9.2 | 810 | 2/16/2019 |
1.9.1 | 788 | 2/10/2019 |
1.9.0 | 808 | 2/2/2019 |
1.8.2 | 978 | 1/28/2019 |
1.8.1 | 1,003 | 1/10/2019 |
1.8.0 | 1,069 | 1/2/2019 |
1.7.0 | 897 | 12/15/2018 |
1.6.2 | 979 | 10/14/2018 |
1.6.1 | 954 | 9/9/2018 |
1.6.0 | 1,053 | 9/2/2018 |
1.5.7 | 1,024 | 8/25/2018 |
1.5.6 | 1,160 | 6/12/2018 |
1.5.5 | 1,118 | 4/2/2018 |
1.5.4 | 1,306 | 3/24/2018 |
1.5.3 | 1,172 | 3/17/2018 |
1.5.2 | 1,260 | 1/3/2018 |
1.5.1 | 1,082 | 9/15/2017 |
1.5.0 | 1,071 | 9/11/2017 |
1.4.2 | 1,046 | 9/7/2017 |
1.4.1 | 1,087 | 8/30/2017 |
1.4.0 | 1,044 | 8/26/2017 |
1.3.0 | 1,135 | 8/20/2017 |
1.2.8 | 1,176 | 5/17/2017 |
1.2.7 | 1,159 | 2/23/2017 |
1.2.6 | 1,141 | 2/13/2017 |
1.2.5 | 1,132 | 2/10/2017 |
1.2.4 | 1,227 | 1/24/2017 |
1.2.3 | 1,277 | 1/2/2017 |
1.2.2 | 1,131 | 12/28/2016 |
1.2.1 | 1,189 | 12/25/2016 |
1.2.0 | 1,229 | 12/18/2016 |
1.1.0 | 1,231 | 12/15/2016 |
1.0.4 | 1,188 | 12/12/2016 |
1.0.3 | 1,211 | 11/29/2016 |
1.0.2 | 1,163 | 11/10/2016 |
1.0.1 | 1,271 | 11/3/2016 |
1.0.0 | 1,196 | 10/24/2016 |
0.10.0 | 1,187 | 10/11/2016 |
0.9.0 | 1,173 | 10/1/2016 |
0.8.1 | 1,160 | 9/28/2016 |
0.8.0 | 1,461 | 9/26/2016 |
0.7.1 | 1,148 | 9/24/2016 |
0.7.0 | 1,270 | 9/22/2016 |
0.6.0 | 1,442 | 9/19/2016 |
0.5.0 | 1,352 | 9/18/2016 |
0.4.1 | 1,119 | 9/15/2016 |
0.4.0 | 1,160 | 9/14/2016 |
0.3.4 | 1,180 | 9/10/2016 |
0.3.3 | 1,143 | 9/8/2016 |
0.3.2 | 1,126 | 9/7/2016 |
0.3.1 | 1,106 | 9/6/2016 |
0.3.0 | 1,140 | 9/5/2016 |
0.2.0 | 1,116 | 9/3/2016 |
0.1.0 | 1,178 | 8/28/2016 |
0.0.2 | 1,175 | 8/26/2016 |
0.0.1 | 1,211 | 8/24/2016 |