{"id":15060944,"url":"https://github.com/chrispritchard/fsh","last_synced_at":"2025-04-09T22:15:55.836Z","repository":{"id":34277758,"uuid":"168986273","full_name":"ChrisPritchard/FSH","owner":"ChrisPritchard","description":"F# Shell with integrated F# scripting. Like Bash or Powershell, but better 'cause F#.","archived":false,"fork":false,"pushed_at":"2022-08-16T00:23:59.000Z","size":185,"stargazers_count":259,"open_issues_count":4,"forks_count":12,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-09T22:15:51.634Z","etag":null,"topics":["applied-fsharp-2019","dotnet-core","fsharp","shell"],"latest_commit_sha":null,"homepage":"","language":"F#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisPritchard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-03T19:49:19.000Z","updated_at":"2025-03-02T10:08:35.000Z","dependencies_parsed_at":"2022-08-08T00:15:22.564Z","dependency_job_id":null,"html_url":"https://github.com/ChrisPritchard/FSH","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisPritchard%2FFSH","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisPritchard%2FFSH/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisPritchard%2FFSH/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisPritchard%2FFSH/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisPritchard","download_url":"https://codeload.github.com/ChrisPritchard/FSH/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119287,"owners_count":21050755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["applied-fsharp-2019","dotnet-core","fsharp","shell"],"created_at":"2024-09-24T23:07:09.161Z","updated_at":"2025-04-09T22:15:55.797Z","avatar_url":"https://github.com/ChrisPritchard.png","language":"F#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FSH\n\n[![Nuget](https://img.shields.io/nuget/v/FSH.svg?maxAge=0\u0026colorB=brightgreen)](https://www.nuget.org/packages/FSH)\n\nFSH (**F**# **Sh**ell - pronounced like 'fish') is a shell, like CMD, Powershell or Bash, entirely written in F#.\n\n\u003e **Update:** Recently upgraded to NET 5, no issues so far!\n\n\u003e **Update Update:** And now its NET 6, poggers\n\n\u003e Note this is sort of a proof of concept, which while functional (ha), lacks a lot of functionality compared to a regular shell like bash, powershell or even cmd (e.g. `ls`, but no `ls -la`). But... you can run F#, so thats cool :)\n\n## Basic Interactions\n\nIn addition to normal shell features (folder navigation, creation, deletion, echo etc.), FSH also supports piping and F# interactive. You can run code to declare F# functions, then use those functions as part of a piping operation with the other builtin commands. You can also just declare anonymous expressions for piping.\n\nTo demonstrate what this means, using FSH, you could type a line like:\n\n\techo hello world |\u003e (fun s -\u003e s.ToUpper()) \u003e result.txt\n\nWhich would create a text file in the current directory called result.txt, containing the text `HELLO WORLD`\n\nYou can see in the above sample that to pipe between processable 'tokens' (like a command or code) you use `|\u003e` just like in F#. And to run F# code, you wrap it with `(` and `)`. In the sample the built-in command `echo` with the arguments `hello world` is piped to the code expression `fun s -\u003e s.ToUpper()`, then piped again to the result.txt file (`\u003e` is a special pipe that sends to a file rather than console out - \u003e\u003e is also supported to append rather than overrite).\n\nAs you type the above, the text is coloured automatically by the type of expression you are typing.\n\n## Further Examples\n\nFor something more advanced, you could implement a simple 'grep' command (grep is not built in to FSH by default):\n\n\t(let grep (s:string) arr = \n\t\tarr |\u003e Array.filter (fun line -\u003e line.Contains(s)))\n\n(**Note:** that shift/alt/control+enter will go to a new line, useful for code. Tabbing (four spaces) works as well, shunting the current line forward. Also, by piping arr on the second line, the line parameter does not need a type annotation.)\n\n(**Further Note for Linux/OSX:** the terminal and System.Console.ConsoleModifiers don't work very well together, so aside from shift, control and alt also work with enter for new lines. Find what works for you - alt+enter worked for me on Ubuntu)\n\n(**Further Further Note for Linux/OSX:** there is an issue with newlines on these platforms, due to inconsistencies between how System.Console, TextWriter, CursorTop (or something) work. I am presently investigating these issues (issue #10 and #14))\n\nThen use this like:\n\n\tls |\u003e (grep \".dll\")\n\nThis will list all dll files in the current directory, one per line.\n\nThis can be used with any token, not just 'built-ins' like `echo` and `ls`. For example, if you wanted to get the list of templates in the dotnet CLI that support F#:\n\n\tdotnet new |\u003e (fun sa -\u003e sa |\u003e Seq.filter (fun s -\u003e s.Contains \"F#\"))\n\nOn my machine, this will print:\n\n\tConsole Application                               console            [C#], F#, VB      Common/Console                   \n\tClass library                                     classlib           [C#], F#, VB      Common/Library                   \n\tUnit Test Project                                 mstest             [C#], F#, VB      Test/MSTest                      \n\t... and so on\n\n## Installing and Running\n\nFSH uses **.NET 5**. To build, you will need to install this SDK from [here](https://dotnet.microsoft.com/download/dotnet/5.0).\n\nIt has been tested in Linux (via Ubuntu 18 under WSL and on a VM) and on Max OSX, with some minor issues (see [Issues](https://github.com/ChrisPritchard/FSH/issues) here on github).\n\nTo run on the command line, navigate to the **/src** directory and use the command `dotnet run`\n\nThere are also some XUnit/FsUnit tests defined under /test, there for testing various input scenarios through the parts/tokenisation functions. Run them (if you wish) via `dotnet test` in the **/test** directory.\n\n**Important**: This was built in a month, and shells are a lot more complicated than they look. There *are* bugs, but *hopefully* during casual use you won't find them :)\n\n## \"Builtins\"\n\nAny shell has a number of commands that you can run, aside from things like external processes or in the case of FSH, code. FSH supports a limited set of these, all with basic but effective functionality. To get a list of these type **help** or **?**. Some common examples are:\n\n- **cd [path]**: change the current directory. E.g. `cd /` or `cd ..` to go to root or one directory up.\n- **echo [text]**: prints the arguments out as text - quite useful for piping\n- **cat [filename]** reads a file and prints out its output - also useful for piping\n- **\u003e [filename]** prints out the piped in content into a file (this overwrites; **\u003e\u003e** appends instead).\n\nThere are almost a dozen further commands, like **rm**, **mkdir**, **env** etc. As mentioned in the intro, these commands do their very basic functions, and don't support the arguments you would expect from a regular shell, but they serve to prove the concept.\n\nAll builtins are defined in [Builtins.fs](/src/Builtins.fs)\n\n## Code expressions\n\nCode expressions are written by wrapping code with `(` and `)`. Only the outer most parentheses are parsed as wrappers, so for example `(fun (s:string) -\u003e s.ToUpper())` is perfectly fine. \n\nIf a code expression is the first expression on a line, then it is treated as a **FSI Interaction**. Otherwise it is treated as a **FSI Expression**. What is the difference?\n\n- A FSI Interaction can be any valid F# code. `let x = 10`, `50 * 5`, `let grep (s: string) arr = arr |\u003e Array.filter (fun line -\u003e line.Contains(s))` are all valid interactions.\n- A FSI Expression must be F# that evaluates to a value. `let x = 10` is not a valid expression, but `let x = 10 in x` *is* valid as it will evaluate to 10. Likewise, defining functions like `let grep ...` above is not valid unless it is immediately used in a `in` expression, like `let grep... in grep \".dll\"` (which will also locally scope grep, making it not usable again without being redefined).\n\n### Piped values\n\nBecause expressions are only run when there is a value to be piped into them, in FSH they have the additional contraint that they must support a parameter that matches the piped value (either a string or a string array). The reason is that in `echo \"test\" |\u003e (fun s -\u003e s.ToUpper())`, the code that is passed to the hidden FSI process is actually `let piped = \"test\" in piped |\u003e (fun s -\u003e s.ToUpper())`\n\nNormally the piped value will be a string, as above. However if the prior result contains line breaks, it will be split into an array. E.g. ls or dir, if used on a directory with more than one file, will produce a piped string array for code expressions to use.\n\nAn expression can return either a value or a string array. If the latter, than it will be concatenated with line breaks for output printing. Otherwise it is converted to a string.\n\n### Loading or composing code\n\nThere is a special code expression, `(*)`. When This token is parsed, it treats the *piped value as code*.\n\nFor example, say you ran this line:\n\n\techo printfn \"hello world from FSH!\" \u003e greeter.fs\n\nYou could then read and evaluate this file using:\n\n\tcat greeter.fs |\u003e (*)\n\nResulting in the output \"hello world from FSH!\" being printed to the console.\nLikewise, you could compose without a file, like:\n\n\techo printfn \"FSH says Hello World\" |\u003e (*)\n\nTo get \"FSH says Hello World!\" printed to the console.\n\n### Interactions and 'it'\n\nBy default, FSI will evaluate an interaction and return `unit` if successful. \nIn order to make interactions useful as the first token of a piped expression, after an interaction is evaluated FSH will attempt to evaluate the expression 'it' and send its value on to the next token (or console out, if the last expression).\n\nIf this evaluation fails, then an empty string is passed along. Otherwise, if found, then 'it' is *set* to \"\", before the value is passed along. This is so that 'it', is cleared in case the use of later interaction doesn't overwrite it.\n\nCode is run in [Interactive.fs](/src/Interactive.fs), which wraps FSI. For further details please follow the code in there.\n\n## Why?\n\nThis has been developed for the **[2019 F# Applied Competition](http://foundation.fsharp.org/applied_fsharp_challenge)**, as an educational project, over the course of about a month. \n\n\u003e **Update:** It won in one of the competition categories, I am proud to say. Full results [here](http://foundation.fsharp.org/results_applied_fsharp_2019).\n\nThe idea came from PowerShell, which as a developer who works primarily on windows machines, is my default shell. However, PowerShell syntax is very verbose, especially when using .NET code in-line; a shell with a simpler, more bash- or cmd-like syntax combined with the light syntax and type inferrence of F# seemed like a good thing to make into a proof-of-concept.\n\nAs it stands, FSH is not really intended to be used in anger: while it supports a host of builtins, and is quite extensible with its FSI integration, it is missing a lot of features, for example numerous flags on the default builtins (ls/dir just list the local directory, but don't for example, have any flags to provide more info or multi page support etc).\n\nIf someone wanted to take this, and extend it, they are free to do so: its under MIT. But primarily FSH serves as an educational example of:\n\n- Creating a shell, able to run its own commands and external executables.\n- Various folder and file manipulation techniques.\n- A custom ReadLine method, that supports advanced features like line shifting and history (defined in [LineReader.fs](/src/LineReader.fs))\n- String tokensisation (defined in [LineParser.fs](/src/LineParser.fs))\n- Integrating F# Interactive into a project in a useful way.\n\nAll code files are helpfully commented. Start with [Program.fs](/src/Program.fs) and follow its structure from there.\n\nI hope it is useful to readers on the above topics :)\n\n**Finally**: I know there is another shell called 'fish' out there (the **[Friendly Interactive Shell](https://github.com/fish-shell/fish-shell)**). But what else would I call a F# Shell but FSH?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrispritchard%2Ffsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrispritchard%2Ffsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrispritchard%2Ffsh/lists"}