mirror of
https://github.com/carp-lang/Carp.git
synced 2024-09-17 08:27:45 +03:00
docs: Remove a lot of duplicated information and refer to webpages instead (#988)
* docs: Remove a lot of duplicated information and refer to webpages instead * fix: Remove line about (help), it does not make sense anymore * fix: Add open-browser to nix config Co-authored-by: Erik Svedang <erik@Eriks-iMac.local>
This commit is contained in:
Erik Svedäng
GitHub
parent
8cc2ae1f2b
commit
793bf19ede
@ -72,6 +72,7 @@ library
|
||||
, ansi-terminal >= 0.10.3
|
||||
, cmark
|
||||
, edit-distance
|
||||
, open-browser
|
||||
|
||||
default-language: Haskell2010
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ let
|
||||
linuxOnly = optionals nixpkgs.stdenv.isLinux;
|
||||
|
||||
f = { mkDerivation, stdenv
|
||||
, ansi-terminal, base, blaze-html, blaze-markup
|
||||
, ansi-terminal, open-browser, base, blaze-html, blaze-markup
|
||||
, cmark, containers, directory, edit-distance, filepath
|
||||
, haskeline, HUnit, mtl, optparse-applicative, parsec, process, split, text
|
||||
, darwin, glfw3, SDL2, SDL2_image, SDL2_gfx, SDL2_mixer, SDL2_ttf
|
||||
@ -35,7 +35,7 @@ let
|
||||
enableLibraryProfiling = profiling;
|
||||
enableExecutableProfiling = profiling;
|
||||
libraryHaskellDepends = [
|
||||
ansi-terminal base blaze-html blaze-markup cmark containers
|
||||
ansi-terminal open-browser base blaze-html blaze-markup cmark containers
|
||||
directory edit-distance filepath haskeline mtl parsec process split
|
||||
text
|
||||
] ++ optionals profiling [ ghc-prof-flamegraph ];
|
||||
|
||||
@ -16,8 +16,6 @@ To learn more about the Carp language and its syntax and semantics, check out th
|
||||
|
||||
The Carp language is very tightly integrated with the REPL, everything you want to do to your program can be controlled from here.
|
||||
|
||||
To explore the commands available, enter ```(help)``` and press enter.
|
||||
|
||||
To load code from disk, use ```(load "filename.carp")```, this will add the source file `filename.carp` to the current 'project'. A project is a light weight concept in the repl that ties together source files and compiler settings much like in an IDE like Eclipse or Visual Studio.
|
||||
|
||||
To build your current project, call ```(build)```. This will emit an executable or dynamic library depending on if you have defined a main-function or not. Please note that a project emitting a library will not initialize global variables automatically, the user of the library needs to call the C function `carp_init_globals` or the Carp function `System.carp-init-globals` instead.
|
||||
|
||||
180
src/Commands.hs
180
src/Commands.hs
@ -295,186 +295,6 @@ commandListBindings ctx args =
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
-- | Command for printing help.
|
||||
commandHelp :: CommandCallback
|
||||
commandHelp ctx [XObj (Str "about") _ _] =
|
||||
liftIO $ do putStrLn "Carp is an ongoing research project by Erik Svedäng, et al."
|
||||
putStrLn ""
|
||||
putStrLn "Licensed under the Apache License, Version 2.0 (the \"License\"); \n\
|
||||
\you may not use this file except in compliance with the License. \n\
|
||||
\You may obtain a copy of the License at \n\
|
||||
\http://www.apache.org/licenses/LICENSE-2.0"
|
||||
putStrLn ""
|
||||
putStrLn "THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY \n\
|
||||
\EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE \n\
|
||||
\IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR \n\
|
||||
\PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE \n\
|
||||
\LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR \n\
|
||||
\CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF \n\
|
||||
\SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR \n\
|
||||
\BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, \n\
|
||||
\WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE \n\
|
||||
\OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN\n\
|
||||
\IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj (Str "language") _ _] =
|
||||
liftIO $ do putStrLn "Special forms:"
|
||||
putStrLn "(if <condition> <then> <else>)"
|
||||
putStrLn "(while <condition> <body>)"
|
||||
putStrLn "(do <statement1> <statement2> ... <exprN>)"
|
||||
putStrLn "(let [<sym1> <expr1> <name2> <expr2> ...] <body>)"
|
||||
putStrLn "(fn [<args>] <body>)"
|
||||
putStrLn "(the <type> <expression>)"
|
||||
putStrLn "(ref <expression>)"
|
||||
putStrLn "(address <expr>)"
|
||||
putStrLn "(set! <var> <value>)"
|
||||
putStrLn "(break)"
|
||||
putStrLn ""
|
||||
putStrLn "To use functions in modules without qualifying them:"
|
||||
putStrLn "(use <module>)"
|
||||
putStrLn "(with <module> <form>)"
|
||||
putStrLn ""
|
||||
putStrLn ("Valid non-alphanumerics: " ++ validCharacters)
|
||||
putStrLn ""
|
||||
putStrLn "Number literals:"
|
||||
putStrLn "1 Int"
|
||||
putStrLn "1l Long"
|
||||
putStrLn "1.0 Double"
|
||||
putStrLn "1.0f Float"
|
||||
putStrLn ""
|
||||
putStrLn "Reader macros:"
|
||||
putStrLn "&<expr> (ref <expr>)"
|
||||
putStrLn "@<expr> (copy <expr>)"
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj (Str "macros") _ _] =
|
||||
liftIO $ do putStrLn "To inspect what macros expand to:"
|
||||
putStrLn "(expand <quoted expression>)"
|
||||
putStrLn ""
|
||||
putStrLn "Some useful macros:"
|
||||
putStrLn "(cond <condition1> <expr1> ... <else-condition>)"
|
||||
putStrLn "(case <expr> <compare-this-1> <expr1> ... <else-condition>)"
|
||||
putStrLn "(when <condition> <body>)"
|
||||
putStrLn "(for [<var> <from> <to>] <body>)"
|
||||
putStrLn "(=> <expr> <func1> <func2> ...)"
|
||||
putStrLn "(==> <expr> <func1> <func2> ...)"
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj (Str "structs") _ _] =
|
||||
liftIO $ do putStrLn "To define a struct without any generic member variables:"
|
||||
putStrLn "(deftype <name> [<member> <type>, ...])"
|
||||
putStrLn ""
|
||||
putStrLn "If you need generic members:"
|
||||
putStrLn "(deftype (<name> <type variable 1> ...) [<member> <type>, ...])"
|
||||
putStrLn ""
|
||||
putStrLn "A type definition will generate the following methods:"
|
||||
putStrLn "Getters (<method-name> (Ref <struct>))"
|
||||
putStrLn "Setters (set-<method-name> <struct> <new-value>)"
|
||||
putStrLn "Updaters (update-<method-name> <struct> <new-value>)"
|
||||
putStrLn "init (stack allocation)"
|
||||
putStrLn "new (heap allocation)"
|
||||
putStrLn "copy"
|
||||
putStrLn "delete (used internally, no need to call this explicitly)"
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj(Str "shortcuts") _ _] =
|
||||
liftIO $ do putStrLn "GHC-style shortcuts at the repl:"
|
||||
putStrLn "(reload) :r"
|
||||
putStrLn "(build) :b"
|
||||
putStrLn "(run) :x"
|
||||
putStrLn "(cat) :c"
|
||||
putStrLn "(env) :e"
|
||||
putStrLn "(help) :h"
|
||||
putStrLn "(project) :p"
|
||||
putStrLn "(quit) :q"
|
||||
putStrLn "(type <arg>) :t"
|
||||
putStrLn "(expand <arg>) :m"
|
||||
putStrLn "(info <arg>) :i"
|
||||
putStrLn ""
|
||||
putStrLn "The shortcuts can be combined like this: \":rbx\""
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj(Str "interop") _ _] =
|
||||
liftIO $ do putStrLn "(register <name> <type>) - Make an external variable or function available for usage."
|
||||
putStrLn "(register-type <name> [<member> <type>, ...]) - Make an external struct available for usage."
|
||||
putStrLn ""
|
||||
putStrLn "C-compiler configuration:"
|
||||
putStrLn "(system-include <file>) - Include a system header file."
|
||||
putStrLn "(local-include <file>) - Include a local header file."
|
||||
putStrLn "(add-cflag <flag>) - Add a cflag to the compilation step."
|
||||
putStrLn "(add-lib <flag>) - Add a library flag to the compilation step."
|
||||
putStrLn "(add-c <flag>) - Add a C/ObjC/C++ module to the compilation step."
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [XObj(Str "project") _ _] =
|
||||
liftIO $ do putStrLn "(Project.config <setting> <value>) handles the following settings:"
|
||||
putStrLn ""
|
||||
putStrLn "'cflag' - Add a flag to the compiler."
|
||||
putStrLn "'libflag' - Add a library flag to the compiler."
|
||||
putStrLn "'pkgconfigflag' - Add a flag to pkg-config invocations."
|
||||
putStrLn "'cmod' - Add a C/ObjC/C++ module to the compiler invocation."
|
||||
putStrLn "'compiler' - Set what compiler should be run with the 'build' command."
|
||||
putStrLn "'title' - Set the title of the current project, will affect the name of the binary produced."
|
||||
putStrLn "'output-directory' - Where to put compiler artifacts, etc."
|
||||
putStrLn "'docs-directory' - Where to put generated documentation."
|
||||
putStrLn "'docs-logo' - Location of the documentation logo."
|
||||
putStrLn "'docs-prelude' - The documentation foreword."
|
||||
putStrLn "'docs-url' - A URL for the project (useful for generated documentation)."
|
||||
putStrLn "'docs-generate-index' - Whether to generate the documentation index."
|
||||
putStrLn "'docs-styling' - A URL to CSS for the project documentation."
|
||||
putStrLn "'prompt' - Set the prompt in the repl."
|
||||
putStrLn "'search-path' - Add a path where the Carp compiler will look for '*.carp' files."
|
||||
putStrLn ""
|
||||
putStrLn "'echo-c' - When a form is defined using 'def' or 'defn' its C code will be printed."
|
||||
putStrLn "'echo-compiler-cmd' - When building the project the command for running the C compiler will be printed."
|
||||
putStrLn "'print-ast' - The 'info' command will print the AST for a binding."
|
||||
putStrLn "'paren-balance-hints' - Whether to print the ongoing stack of parens to close in the REPL, or not."
|
||||
putStrLn "'force-reload' - If true, the 'load-once' command will work just like 'load' (useful for library developers)."
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx [] =
|
||||
liftIO $ do putStrLn "Compiler commands:"
|
||||
putStrLn "(load <file>) - Load a .carp file, evaluate its content, and add it to the project."
|
||||
putStrLn "(reload) - Reload all the project files."
|
||||
putStrLn "(build) - Produce an executable or shared library."
|
||||
putStrLn "(run) - Run the executable produced by 'build' (if available)."
|
||||
putStrLn "(cat) - Look at the generated C code (make sure you build first)."
|
||||
putStrLn "(env) - List the bindings in the global environment."
|
||||
putStrLn "(type <symbol>) - Get the type of a binding."
|
||||
putStrLn "(info <symbol>) - Get information about a binding."
|
||||
putStrLn "(project) - Display information about your project."
|
||||
putStrLn "(quit) - Terminate this Carp REPL."
|
||||
putStrLn "(help <chapter>) - Available chapters: \"language\", \"macros\", \"structs\", \"interop\", \"shortcuts\", \"project\", \"about\"."
|
||||
putStrLn ""
|
||||
putStrLn "(Project.config! <setting> <value>) - Change a project setting."
|
||||
putStrLn ""
|
||||
putStrLn "To define things:"
|
||||
putStrLn "(def <name> <constant>) - Define a global variable."
|
||||
putStrLn "(defn <name> [<args>] <body>) - Define a function."
|
||||
putStrLn "(definterface <name> <type>) - Create an interface for a group of functions sharing the same name."
|
||||
putStrLn "(defmodule <name> <def1> <def2> ...) - Define a module and/or add definitions to an existing one."
|
||||
putStrLn "(deftype <name> [<member> <type>, ...]) - Define a new struct type."
|
||||
putStrLn ""
|
||||
putStrLn "Compiler flags:"
|
||||
putStrLn "-b - Build."
|
||||
putStrLn "-x - Build and run."
|
||||
putStrLn "--no-core - Don't load the core library."
|
||||
putStrLn "--log-memory - Enables use of memory logging functions in the Debug module."
|
||||
putStrLn "--optimize - Removes safety checks and runs the C-compiler with the '-O3' flag."
|
||||
putStrLn "--check - Report all errors found in a machine readable way."
|
||||
putStrLn "--generate-only - Don't compile the C source."
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
commandHelp ctx args =
|
||||
return (evalError ctx ("Invalid args to `help` command: " ++ joinWithComma (map pretty args)) Nothing)
|
||||
|
||||
-- | Command for printing information about the current project.
|
||||
commandProject :: CommandCallback
|
||||
commandProject ctx args = do
|
||||
|
||||
@ -5,6 +5,7 @@ import Control.Monad.IO.Class (liftIO)
|
||||
import Data.List (foldl')
|
||||
import Data.Maybe (fromMaybe)
|
||||
import Data.Either (isRight, rights)
|
||||
import Web.Browser (openBrowser)
|
||||
|
||||
import ColorText
|
||||
import Commands
|
||||
@ -690,3 +691,78 @@ primitiveKind _ ctx [x@(XObj _ _ _)] =
|
||||
where fail e = (evalError ctx ("Can't get the kind of: " ++ pretty x) (info x))
|
||||
ok (XObj _ _ (Just t), _) = (ctx, Right $ reify (tyToKind t))
|
||||
ok (_, _) = (evalError ctx ("Can't get the kind of: " ++ pretty x) (info x))
|
||||
|
||||
-- | Primitive for printing help.
|
||||
primitiveHelp :: Primitive
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "about") _) _ _] =
|
||||
liftIO $ do putStrLn "Carp is an ongoing research project by Erik Svedäng, et al."
|
||||
putStrLn ""
|
||||
putStrLn "Licensed under the Apache License, Version 2.0 (the \"License\"); \n\
|
||||
\you may not use this file except in compliance with the License. \n\
|
||||
\You may obtain a copy of the License at \n\
|
||||
\http://www.apache.org/licenses/LICENSE-2.0"
|
||||
putStrLn ""
|
||||
putStrLn "THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY \n\
|
||||
\EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE \n\
|
||||
\IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR \n\
|
||||
\PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE \n\
|
||||
\LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR \n\
|
||||
\CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF \n\
|
||||
\SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR \n\
|
||||
\BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, \n\
|
||||
\WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE \n\
|
||||
\OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN\n\
|
||||
\IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "compiler") _) _ _] =
|
||||
openBrowserHelper ctx "https://github.com/carp-lang/Carp/blob/master/docs/Manual.md"
|
||||
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "language") _) _ _] =
|
||||
openBrowserHelper ctx "https://github.com/carp-lang/Carp/blob/master/docs/LanguageGuide.md"
|
||||
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "core") _) _ _] =
|
||||
openBrowserHelper ctx "https://carp-lang.github.io/carp-docs/core/core_index.html"
|
||||
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "gitter") _) _ _] =
|
||||
openBrowserHelper ctx "https://gitter.im/carp-lang/Carp"
|
||||
|
||||
primitiveHelp _ ctx [XObj (Sym (SymPath [] "shortcuts") _) _ _] =
|
||||
liftIO $ do putStrLn ""
|
||||
putStrLn "(reload) :r"
|
||||
putStrLn "(build) :b"
|
||||
putStrLn "(run) :x"
|
||||
putStrLn "(cat) :c"
|
||||
putStrLn "(env) :e"
|
||||
putStrLn "(help) :h"
|
||||
putStrLn "(project) :p"
|
||||
putStrLn "(quit) :q"
|
||||
putStrLn "(type <arg>) :t"
|
||||
putStrLn "(expand <arg>) :m"
|
||||
putStrLn "(info <arg>) :i"
|
||||
putStrLn ""
|
||||
putStrLn "The shortcuts can be combined like this: \":rbx\""
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
primitiveHelp _ ctx [] =
|
||||
liftIO $ do putStrLn "Don't panic - we can solve this!"
|
||||
putStrLn ""
|
||||
putStrLn "Evaluate (help <chapter>) to get to the relevant subchapter:"
|
||||
putStrLn ""
|
||||
putStrLn "compiler - Learn how to use the compiler / repl (web)"
|
||||
putStrLn "language - Syntax and semantics of the language (web)"
|
||||
putStrLn "core - Core library API documentation (web)"
|
||||
putStrLn "gitter - Get help from the community (web)"
|
||||
putStrLn "shortcuts - Useful shortcuts in the REPL "
|
||||
putStrLn "about - Print some information about this program "
|
||||
putStrLn ""
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
primitiveHelp _ ctx args =
|
||||
return (evalError ctx ("Invalid args to `help`: " ++ joinWithComma (map pretty args)) Nothing)
|
||||
|
||||
openBrowserHelper ctx url =
|
||||
liftIO $ do openBrowser url
|
||||
return (ctx, dynamicNil)
|
||||
|
||||
@ -215,7 +215,6 @@ dynamicModule = Env { envBindings = bindings
|
||||
, addCommand (SymPath path "build") 0 (commandBuild False) "builds the current code to an executable." "(build)"
|
||||
, addCommand (SymPath path "reload") 0 commandReload "reloads all currently loaded files that weren’t marked as only loading once (see `load` and `load-once`)." "(reload)"
|
||||
, addCommand (SymPath path "env") 0 commandListBindings "lists all current bindings." "(env)"
|
||||
, addCommandConfigurable (SymPath path "help") Nothing commandHelp "prints help." "(help)"
|
||||
, addCommand (SymPath path "project") 0 commandProject "prints the current project state." "(project)"
|
||||
, addCommand (SymPath path "load") 1 commandLoad "loads a file into the current environment." "(load \"myfile.carp\")"
|
||||
, addCommand (SymPath path "load-once") 1 commandLoadOnce "loads a file and prevents it from being reloaded (see `reload`)." "(load-once \"myfile.carp\")"
|
||||
@ -252,6 +251,7 @@ dynamicModule = Env { envBindings = bindings
|
||||
, makePrim "implements" 2 "designates a function as an implementation of an interface." "(implements zero Maybe.zero)" primitiveImplements
|
||||
, makePrim "type" 1 "prints the type of a symbol." "(type mysymbol)" primitiveType
|
||||
, makePrim "kind" 1 "prints the kind of a symbol." "(kind mysymbol)" primitiveKind
|
||||
, makeVarPrim "help" "prints help." "(help)" primitiveHelp
|
||||
]
|
||||
++ [("String", Binder emptyMeta (XObj (Mod dynamicStringModule) Nothing Nothing))
|
||||
,("Symbol", Binder emptyMeta (XObj (Mod dynamicSymModule) Nothing Nothing))
|
||||
|
||||
Loading…
Reference in New Issue
Block a user