core
Below is a runthrough of all of the documentation pertaining to running a Toolips server.
connection
Toolips.Connection
— TypeConnection <: AbstractConnection
- routes::Dict
- http::HTTP.Stream
- extensions::Dict
The connection type is passed into route functions and pages as an argument. This is both for functions, as well as Servable.f() methods. This constructor should not be called directly. Instead, it is called by the server and passed through the function pipeline. Indexing a Connection will return the extension named with that symbol.
example
# v The Connection
home = route("/") do c::Connection
c[Logger].log(1, "We can index extensions by type or symbol")
c[:logger].log(1, "see?")
c.routes["/"] = c::Connection -> write!(c, "rerouting!")
httpstream = c.http
write!(c, "Hello world!")
myheading::Component = h("myheading", 1, text = "Whoa!")
write!(c, myheading)
end
field info
- routes::Dict - A dictionary of routes where the keys
are the routed URL and the values are the functions to those keys.
- http::HTTP.Stream - The stream for this current peer's connection.
- extensions::Dict - A dictionary of extensions to load with the
name to reference as keys and the extension as the pair.
constructors
- Connection(routes::Dict, http::HTTP.Stream, extensions::Dict)
Connections are served as an argument to incoming routes. Functions are written anticipating a connection return. Here we will write a new route using the route(::Function, ::String) method.
Route("/", Main.EvalBlockSandbox.var"#1#2"())We also use the write!() method on our Connection. We can use this on the types ::Any, ::Vector{Servable}, and ::Servable.
Toolips.write!
— FunctionInterface
write!(c::AbstractConnection, s::Servable) -> _
Writes a Servable's return to a Connection's stream. This is usually used in a routing function or a route where ::Connection is provided as an argument.
example
serv = p("mycomp", text = "hello")
rt = route("/") do c::Connection
write!(c, serv)
end
Interface
write!(c::AbstractConnection, s::Vector{Servable}) -> _
Writes all servables in s to c.
example
c = Component()
c2 = Component()
comps = components(c, c2)
Vector{Servable}(Component(), Component())
write!(c, comps)
Interface
write!(c::AbstractConnection, s::String) -> _
Writes the String into the Connection as HTML.
example
write!(c, "hello world!")
Interface
write!(::AbstractConnection, ::Any) -> _
Attempts to write any type to the Connection's stream.
example
d = 50
write!(c, d)
Or push any data response into a body and startread the body.
Base.push!
— MethodInterface
push!(c::AbstractConnection, data::Any) -> _
A "catch-all" for pushing data to a stream. Produces a full response with data as the body.
example
Toolips.startread!
— MethodInterface
startread!(::AbstractConnection) -> _
Resets the seek on the Connection. This function is only meant to be used on post bodies.
example
post = getpost(c)
"hello"
post = getpost(c)
""
startread!(c)
post = getpost(c)
"hello"
Toolips.extensions
— MethodInterface
extensions(c::Connection) -> ::Dict{Symbol, ServerExtension}
Returns the server's extensions.
example
route("/") do c::Connection
extensions(c)
end
Toolips.routes
— MethodInterface
routes(c::Connection) -> ::Dict{String, Function}
Returns the server's routes.
example
route("/") do c::Connection
routes(c)
end
Toolips.has_extension
— MethodInterface
has_extension(c::AbstractConnection, t::Type) -> ::Bool
Checks if c.extensions has an extension of type t.
example
if has_extension(c, Logger)
c[:Logger].log("it has a logger, I think.")
end
The connection type can be indexed with Symbols, Strings, and Types. Symbols and Types will index the extensions. Strings will index the routes. The same goes for setting the indexes.
Base.setindex!
— MethodInterface
setindex!(c::AbstractConnection, f::Function, s::String) -> _
Sets the route path s to serve at the function f.
example
c["/"] = c -> write!(c, "hello")
Base.getindex
— MethodInterface
getindex(c::AbstractConnection, s::Symbol) -> ::ServerExtension
Indexes the extensions in c.
example
route("/") do c::Connection
c[:Logger].log("hi")
end
Base.getindex
— MethodInterface
getindex(c::AbstractConnection, t::Type) -> ::ServerExtension
Indexes the extensions in c by type.
example
route("/") do c::Connection
c[Logger].log("hi")
end
Base.getindex
— MethodInterface
getindex(c::AbstractConnection, s::String) -> ::Function
Returns the function that corresponds to the route dir s.
example
c["/"]
home
We also use the Connection in order to get arguments, download files, and pretty much anything else pertaining to a person's connection.
Toolips.getarg
— FunctionInterface
getarg(c::AbstractConnection, s::Symbol) -> ::Any
Returns the requested argument from the target.
example
getarg(c, :x)
50
Interface
getarg(c::AbstractConnection, s::Symbol, t::Type) -> ::Vector
This method is the same as getargs(::HTTP.Stream, ::Symbol), however types are parsed as type T(). Note that "Cannot convert..." errors are possible with this method.
example
getarg(c, :x, Int64)
50
Toolips.getargs
— FunctionInterface
getargs(c::AbstractConnection) -> ::Dict{Symbol, Any}
The getargs method returns arguments from the HTTP target (GET requests.) Returns a Dict with the argument keys as Symbols.
example
route("/") do c
args = getargs(c)
args[:message]
"welcome to toolips ! :)"
end
Toolips.getip
— FunctionInterface
getip(c::AbstractConnection) -> ::String
Returns the IP that is connected via the connection c.
example
getip(c)
"127.0.0.2"
Toolips.getpost
— FunctionInterface
getpost(c::AbstractConnection) -> ::String
Returns the POST body of c.
example
getpost(c)
"hello, this is a post request"
Toolips.download!
— FunctionInterface
download!(c::AbstractConnection, uri::String) -> _
Downloads a file to a given Connection's computer.
example
download!(c, "files/mytext.txt")
Toolips.navigate!
— FunctionInterface
navigate!(::AbstractConnection, ::String) -> _
Routes a connected stream to a given URL.
example
navigate!(c, "https://github.com/ChifiSource/Toolips.jl")
We can also check if an extension is present by type.
Toolips.has_extension
— MethodInterface
has_extension(c::AbstractConnection, t::Type) -> ::Bool
Checks if c.extensions has an extension of type t.
example
if has_extension(c, Logger)
c[:Logger].log("it has a logger, I think.")
end
routing
When routing, many methods involve the Connection type we just spoke of. In toolips, routes are handled by the Route type.
Toolips.Route
— TypeRoute
- path::String
- page::Function A route is added to a ServerTemplate using either its constructor, or the
ServerTemplate.add(::Route) method. Each route calls a function. The Route type is commonly constructed using the do syntax with the route(::Function, ::String) method.
example
# Constructors
route = Route("/", p(text = "hello"))
function example(c::Connection)
write!(c, "hello")
end
route = Route("/", example)
# method
route = route("/") do c
write!(c, "Hello world!")
write!(c, p(text = "hello"))
# we can also use extensions!
c[:logger].log("hello world!")
end
field info
- path::String - The path to route to the function, e.g. "/".
- page::Function - The function to route the path to.
constructors
- Route(path::String, f::Function)
The Route's constructors are not typically called directly, instead it is probably better to use these methods. Using route! as opposed to route! will modify the routes of a Connection or ToolipsServer
Toolips.route
— FunctionInterface
route(f::Function, r::String) -> ::Route
Creates a route from the Function. The function should take a Connection or AbstractConnection as a single positional argument.
example
route("/") do c::Connection
end
Interface
route(r::String, f::Function) -> ::Route
Creates a route from the Function. The function should take a Connection or AbstractConnection as a single positional argument.
example
function example(c::Connection)
write!(c, h("myh", 1, text = "hello!"))
end
r = route("/", example)
Toolips.route!
— FunctionInterface
route!(c::AbstractConnection, route::Route) -> _
Modifies the route on the Connection.
example
route("/") do c::Connection
r = route("/") do c::Connection
write!(c, "hello")
end
route!(c, r)
end
Interface
route!(::Function, ::AbstractConnection, ::String) -> _
Routes a given String to the Function.
example
route("/") do c
route!(c, "/") do c
println("tacos")
end
end
Interface
route!(f::Function, ws::WebServer, r::String) -> _
Reroutes a server's route r to function f.
example
ws = MyProject.start()
route!(ws, "/") do c
c[:Logger].log("rerouted!")
end
Interface
route!(ws::WebServer, r::String, f::Function) -> _
Reroutes a server's route r to function f.
example
ws = MyProject.start()
function myf(c::Connection)
write!(c, "pasta")
end
route!(ws, "/", myf)
Interface
route!(ws::WebServer, r::Route) -> _
Reroutes a server's route r.
example
ws = MyProject.start()
r = route("/") do c
end
route!(ws, r)
Toolips.unroute!
— FunctionInterface
unroute!(::AbstractConnection, ::String) -> _
Removes the route with the key equivalent to the String.
example
# One request will kill this route:
route("/") do c::Connection
unroute!(c, "/")
end
Toolips.routes
— FunctionInterface
routes(::Route ...) -> ::Vector{Route}
Turns routes provided as arguments into a Vector{Route} with indexable routes. This is useful because this is the type that the ServerTemplate constructor likes. This function is also used as a "getter" for WebServers and Connections, see ?(routes(::WebServer)) & ?(routes(::AbstractConnection))
example
r1 = route("/") do c::Connection
write!(c, "pickles")
end
r2 = route("/pickles") do c::Connection
write!(c, "also pickles")
end
rts = routes(r1, r2)
Interface
routes(ws::WebServer) -> ::Dict{String, Function}
Returns the server's routes.
example
ws = MyProject.start()
routes(ws)
"/" => home
"404" => fourohfour
Interface
routes(c::Connection) -> ::Dict{String, Function}
Returns the server's routes.
example
route("/") do c::Connection
routes(c)
end
servers
ToolipsServers are created by ServerTemplates. Here is a look at how to make a ServerTemplate:
Toolips.ServerTemplate
— TypeServerTemplate
- ip::String
- port::Integer
- routes::Vector{Route}
- extensions::Dict
- remove::Function
- add::Function
- start::Function The ServerTemplate is used to configure a server before
running. These are usually made and started inside of a main server file.
example
st = ServerTemplate()
webserver = ServerTemplate.start()
field info
- ip::String - IP the server should serve to.
- port::Integer - Port to listen on.
- routes::Vector{Route} - A vector of routes to provide to the server
- extensions::Vector{ServerExtension} - A vector of extensions to load into
the server.
- remove(::Int64)::Function - Removes routes by index.
- remove(::String)::Function - Removes routes by name.
- remove(::Symbol)::Function - Removes extension by Symbol representing
type, e.g. :Logger
- add(::Route ...)::Function - Adds the routes to the server.
- add(::ServerExtension ...)::Function - Adds the extensions to the server.
- start()::Function - Starts the server.
constructors
- ServerTemplate(ip::String = "127.0.0.1", port::Int64 = 8001, routes::Vector{Route} = Vector{Route}()); extensions::Vector{ServerExtension} = [Logger()] connection::Type)
The ServerTemplate.start() function returns a sub-type of ToolipsServer.
Toolips.ToolipsServer
— Typeabstract type ToolipsServer
ToolipsServers are returned whenever the ServerTemplate.start() field is called. If you are running your server as a module, it should be noted that commonly a global start() method is used and returns this server, and dev is where this module is loaded, served, and revised.
Consistencies
- routes::Dict - The server's route => function dictionary.
- extensions::Dict - The server's currently loaded extensions.
- server::Any - The server, whatever type it may be...
Toolips.WebServer
— TypeBase.getindex
— MethodInterface
getindex(ws::WebServer, s::Symbol) -> ::ServerExtension
Indexes the extensions in ws.
example
ws = MyProject.start()
ws[:Logger].log("hi")
Toolips.routes
— MethodInterface
routes(ws::WebServer) -> ::Dict{String, Function}
Returns the server's routes.
example
ws = MyProject.start()
routes(ws)
"/" => home
"404" => fourohfour
Toolips.extensions
— MethodInterface
extensions(ws::WebServer) -> ::Dict{Symbol, ServerExtension}
Returns the server's extensions.
example
ws = MyProject.start()
extensions(ws)
:Logger => Logger(blah blah blah)
server extensions
Server extensions are provided to the ServerTemplate type. You may read more about them in the developer api. There are also a few default extensions included with toolips. These can be used by passing them in a Symbol-labeled dictionary as the extensions key-word argument on a ServerTemplate These are Logger and Files.
Toolips.Logger
— TypeLogger <: ServerExtension
- type::Symbol
- out::String
- levels::Dict
- log::Function
- prefix::String
- timeformat::String
- writeat::Int64 A Logger logs information with different levels. Holds the function log(),
connected to the function _log(). Methods.
example
logger = Logger()
st = ServerTemplate(extensions = [Logger()])
r = route("/") do c::Connection
write!(c, "hello world!")
c[:Logger].log("Hello world delivered, mission accomplished.")
end
st.add(r)
st.start()
field info
- type::Symbol - The type of server extension – in this case, Connection.
- out::String - Logfile output directory.
- log(level::Int64, message::String) - Logs the message at the provided level.
- log(message::String) - Logs the message at level 1.
- log(c::Connection, message::String) - Logs to level one and to JavaScript
console.
- levels::Dict - A {Any, Crayon} dict that contains all of the crayons for the
logger. Also contains two special crayons under the keys :timecrayon and :messagecrayon
- prefix::String - The prefix to write before the message.
- timeformat::String - A string representing DT format, must be able to be
passed through the datetime_str macro from Dates.
- writeat::Int64 - The log level to write to out at.
constructors
Logger(levels::Dict{level_count::Int64 => crayon::Crayons.Crayon}; out::String = pwd() * "logs/log.txt") Logger(; out::String = pwd() * "/logs/log.txt")
Toolips.Files
— TypeFiles <: ServerExtension
- type::Symbol
- directory::String
- f::Function Writes all files in directory to their own routes in the server.
field info
- type::Symbol - The type of extension. There are three different selections
you can choose from. :connection :routing :func. A :connection extension will be provided in Connection.extensions. A :routing function is passed a Dict of routes as an argument. The last is a function argument, which is just a specific function to run from the top-end to the server.
- directory::String - The directory to route the files from.
- f::Function - The function f() called with a Connection.
constructors
Files(dir::String)