core

Below is a runthrough of all of the documentation pertaining to running a Toolips server.

connection

Toolips.ConnectionType

Connection <: 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!Function

Interface

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!Method

Interface

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!Method

Interface

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.extensionsMethod

Interface

extensions(c::Connection) -> ::Dict{Symbol, ServerExtension}


Returns the server's extensions.

example

route("/") do c::Connection
    extensions(c)
end
Toolips.routesMethod

Interface

routes(c::Connection) -> ::Dict{String, Function}


Returns the server's routes.

example

route("/") do c::Connection
    routes(c)
end
Toolips.has_extensionMethod

Interface

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!Method

Interface

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.getindexMethod

Interface

getindex(c::AbstractConnection, s::Symbol) -> ::ServerExtension


Indexes the extensions in c.

example

route("/") do c::Connection
    c[:Logger].log("hi")
end
Base.getindexMethod

Interface

getindex(c::AbstractConnection, t::Type) -> ::ServerExtension


Indexes the extensions in c by type.

example

route("/") do c::Connection
    c[Logger].log("hi")
end
Base.getindexMethod

Interface

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.getargFunction

Interface

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.getargsFunction

Interface

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.getipFunction

Interface

getip(c::AbstractConnection) -> ::String


Returns the IP that is connected via the connection c.

example

getip(c)
"127.0.0.2"
Toolips.getpostFunction

Interface

getpost(c::AbstractConnection) -> ::String


Returns the POST body of c.

example

getpost(c)
"hello, this is a post request"
Toolips.download!Function

Interface

download!(c::AbstractConnection, uri::String) -> _


Downloads a file to a given Connection's computer.

example

download!(c, "files/mytext.txt")
Toolips.navigate!Function

Interface

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_extensionMethod

Interface

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.RouteType

Route

  • 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.routeFunction

Interface

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!Function

Interface

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!Function

Interface

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.routesFunction

Interface

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.ServerTemplateType

ServerTemplate

  • 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.ToolipsServerType

abstract 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...
Base.getindexMethod

Interface

getindex(ws::WebServer, s::Symbol) -> ::ServerExtension


Indexes the extensions in ws.

example

ws = MyProject.start()
ws[:Logger].log("hi")
Toolips.routesMethod

Interface

routes(ws::WebServer) -> ::Dict{String, Function}


Returns the server's routes.

example

ws = MyProject.start()
routes(ws)
    "/" => home
    "404" => fourohfour
Toolips.extensionsMethod

Interface

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.LoggerType

Logger <: 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.FilesType

Files <: 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)