Skip to content
Snippets Groups Projects
Commit 4c0ac25d authored by lenkis's avatar lenkis Committed by bigbes
Browse files

Fixes gh-870: slide 10 in tutorial is obsolete 

Revised the entire tutorial (file help_en_US.lua):
 * Tested and fixed all sample code snippets.
 * Corrected typos and inconsistent names in screen headers.
 * Updated info about custom delimiters (screen #6).
 * Replaced box.session with fiber (example on screen #10).
 * Swapped screens #11/#12 (fibers/sockets) for smoother story flow.

Removed help-related stub logic (file help.lua).

Updated auto-tests to expect a new output result on help call.
parent 43eb9ce6
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
src/lua/help.lua
+ 5
− 35
View file @ 4c0ac25d
......@@ -2,46 +2,16 @@ local doc = require('help.en_US')
help = {}
help[1] = {}
help[1]["Help topics"] = { "Basics", "Administration" }
help[2] = "To get help on a topic, type help('topic') (with quotes)"
help[3] = "To get help on a function/object, type help(function) (without quotes)"
help[4] = "To start tutorial, type tutorial()"
help[1] = "To get help, see the Tarantool manual at http://tarantool.org/doc/"
help[2] = "To start the interactive Tarantool tutorial, type 'tutorial()'"
tutorial = {}
tutorial[1] = help[4]
tutorial[1] = help[2]
local help_function_data = {};
help_function_data["Administration"] = {}
help_function_data["Administration"]["Server administrative commands"] =
{ "box.snapshot()",
"box.info()",
"box.stat()",
"box.slab.info()",
"box.slab.check()",
"box.fiber.info()",
"box.plugin.info()",
"box.cfg()",
"box.coredump()"
}
help_function_data["Basics"] = "First thing to be done before any database object can be created, is calling box.cfg() to configure and bootstrap the database instance. Once this is done, define database objects using box.schema, for example type box.schema.space.create('test') to create space 'test'. To add an index on a space, type box.space.test:create_index(). With an index, the space can accept tuples. Insert a tuple with box.space.test:insert{1, 'First tuple'}"
local help_object_data = {}
local function help_call(table, param)
if type(param) == 'string' then
if help_function_data[param] ~= nil then
return help_function_data[param]
end
end
if type(param) == 'table' then
if help_object_data[param] ~= nil then
return help_object_data[param]
end
end
if param ~= nil then
return "Help object not found"
end
return table
return help
end
setmetatable(help, { __call = help_call })
......@@ -73,5 +43,5 @@ setmetatable(tutorial, { __call = tutorial_call })
return {
help = help;
tutorial= tutorial;
tutorial = tutorial;
}
src/lua/help_en_US.lua
+ 76
− 70
View file @ 4c0ac25d
......@@ -39,7 +39,6 @@ When you’re ready to go to the next screen, enter <tutorial("next")>.
Tutorial -- Screen #2 -- Variables
==================================
Improve on "5.1, "Olá", "Lua""
by using variables rather than literals,
and put the strings inside braces, which means
......@@ -52,7 +51,7 @@ you assign to it. Assignment is done with the "=" operator.
If the data type of variable t is table, then the
elements can be referenced as t[1], t[2], and so on.
More in the Lua manual: http://www.lua.org/pil/1.2.html
More in the Lua manual: http://www.lua.org/pil/2.5.html
Request #2 is:
......@@ -65,6 +64,7 @@ Take all three lines and enter them below after the
"tarantool>" prompt, then type Enter.
Or try different values in a different order.
When you’re ready to go to the next screen, enter <tutorial("next")>.
Or, to go to the previous screen, enter <tutorial("prev")>.
]];
[[
......@@ -86,7 +86,7 @@ result_table = {}
n = 5.1
for i=1,2,1 do result_table[i] = n * i end
result_table
--------------------------------------------------------------
------------------------------------------
Take all four lines and enter them below after the
"tarantool>" prompt, then type Enter.
......@@ -136,7 +136,7 @@ Request #5 is:
x = 17
if x * 2 > 34 then result = x else result = "no" end
result
------------------------------------------------
----------------------------------------------------
Before you type in those three lines and see Tarantool display
the result, try to predict whether the display will be
......@@ -156,24 +156,31 @@ which will go over many lines. There is a
Tarantool instruction that means <don’t execute
every time I type Enter; wait until I type a
special string called the "delimiter".>
More in the Tarantool manual: http://tarantool.org/doc/book/administration.html#requests
More in the Tarantool manual:
http://tarantool.org/doc/book/administration.html#requests
Request #6 is:
console = require("console"); console.delimiter("!")
-----------------------------------------------------
----------------------------------------------------
It’s not an exercise -- just do it.
Cancelling the delimiter could be done with
console.delimiter("")!
but you’ll see "!" in following exercises.
You'll need a custom delimiter only in the trial console at
http://try.tarantool.org. Tarantool console in production is smarter.
It can tell when a multi-line request has not ended (for example,
if it sees that a function declaration does not have an end keyword,
as we'll be writing on the next screen).
When you’re ready to go to the next screen, enter <tutorial("next")!>.
Yes, <tutorial("next")!> has to end with an exclamation mark too!
Yes, <tutorial("next")!> now has to end with an exclamation mark too!
]];
[[
Tutorial -- Screen #7 -- Simple Functions
Tutorial -- Screen #7 -- Simple functions
=========================================
A function, or a stored procedure that returns a value,
......@@ -182,13 +189,14 @@ function function_name () body end
More in the Lua manual: http://www.lua.org/pil/5.html
Request #7 is:
n = 0
function func ()
for i=1,100,1 do n = n + i end
return n
end!
func()!
--------------------------------------------------
------------------------------
This defines a function which sums all the numbers
between 1 and 100, and returns the final result.
......@@ -196,7 +204,7 @@ The request "func()!" invokes the function.
]];
[[
Tutorial -- Screen #8 -- Improved Functions
Tutorial -- Screen #8 -- Improved functions
===========================================
Improve the simple function by avoiding globals.
......@@ -212,7 +220,7 @@ for i=1,100,1 do n = n + i end
return n
end!
func(0)!
------------------------------------
------------------------------
]];
[[
......@@ -261,56 +269,26 @@ console = require("console")
At this point, if you just say the variable_name,
you’ll see a list of the package’s members and
functions. If then you use a "." operator as in
package-variable-name . function_name()
package-variable-name.function_name()
you’ll invoke a package’s function.
(At a different level you’ll have to use a ":"
operator, as you’ll see in later examples.)
Request #10 is:
session = require("box.session")!
session!
session.user()!
---------------------------------
First you’ll see a list of functions, one of which
is "user". Then you’ll see the name of the current
user, which happens to be "admin", which happens to
be you.
]];
[[
Tutorial -- Screen #11 -- The socket package
============================================
Connect to the Internet and send a message to the parent of
Tarantool, the mail.ru corporation.
Request #11 is:
function socket_get ()
local socket, sock, result
socket = require("socket")
sock = socket.tcp_connect("mail.ru", 80)
sock:send("GET / HTTP/1.0\r\nHost: mail.ru\r\n\r\n")
result = sock:read(17)
sock:close()
return result
end!
socket_get()!
--------------------------------
fiber = require("fiber")!
fiber!
fiber.status()!
-------------------------
Briefly these requests are opening a socket
and sending a "GET" request to mail.ru’s server.
The response will be short -- "- "HTTP/1.1 302 OK\r\n"" --
but it shows you’ve gotten in touch with a distant server.
More in the Tarantool manual:
http://tarantool.org/doc/reference/socket.html
First you’ll see a list of functions, one of which is "status".
Then you’ll see the fiber's current status (the fiber is running now).
More on fibers on the next screen, so type <tutorial("next")!> now.
]];
[[
Tutorial -- Section #12 -- Fibers
=================================
Tutorial -- Screen #11 -- The fiber package
===========================================
Make a function that will run like a daemon in the
background until you cancel it. For this you need
......@@ -322,12 +300,11 @@ That’s what a properly designed fiber will do.
More in the Tarantool manual:
http://tarantool.org/doc/reference/fiber.html
Request #12 is:
Request #11 is:
fiber = require("fiber")!
gvar = 0!
function function_x()
local i
gvar = 0
for i=0,600,1 do
gvar = gvar + 1
fiber.sleep(1)
......@@ -335,7 +312,7 @@ end
end!
fid = fiber.create(function_x)!
gvar!
-----------------------------
-------------------------------
The fiber.sleep(1) function will go to sleep for
one second, which is one way of yielding.
......@@ -347,8 +324,37 @@ times and notice how the value mysteriously increases.
]];
[[
Tutorial -- Screen #13 -- Tarantool’s box package
=================================================
Tutorial -- Screen #12 -- The socket package
============================================
Connect to the Internet and send a message to Tarantool's web-site.
Request #12 is:
function socket_get ()
local socket, sock, result
socket = require("socket")
sock = socket.tcp_connect("tarantool.org", 80)
sock:send("GET / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")
result = sock:read(17)
sock:close()
return result
end!
socket_get()!
--------------------------------
Briefly these requests are opening a socket
and sending a "GET" request to tarantool.org’s server.
The response will be short, for example
"- "HTTP/1.1 302 OK\r\n""
but it shows you’ve gotten in touch with a distant server.
More in the Tarantool manual:
http://tarantool.org/doc/reference/socket.html
]];
[[
Tutorial -- Screen #13 -- The box package
=========================================
So far you’ve seen Tarantool in action as a
Lua application server. Henceforth you’ll see
......@@ -357,7 +363,7 @@ it as a DBMS (database management system) server
In serious situations you’d have to ask the
database administrator to create database objects
and granted read/write access to you, but here
and grant read/write access to you, but here
you’re the "admin" user -- you have administrative
powers -- so you can start manipulating data immediately.
More in the Tarantool manual:
......@@ -365,7 +371,7 @@ http://tarantool.org/doc/book/box/index.html
Request #13 is:
box.schema.create_space("tutor")!
box.schema.space.create("tutor")!
box.space.tutor:create_index("primary",{})!
box.space.tutor:replace{1,"First tuple"}!
box.space.tutor:replace{2,"Second tuple"}!
......@@ -373,7 +379,7 @@ box.space.tutor:replace{3,"Third tuple"}!
box.space.tutor:replace{4,"Fourth tuple"}!
box.space.tutor:replace{5,"Fifth tuple"}!
box.space.tutor!
----------------
-------------------------------------------
Please ignore all the requests except the last one.
You’ll see a description of a space named tutor.
......@@ -419,7 +425,7 @@ end
return result
end!
database_display("tutor")!
-----------------------------------------------------------------
--------------------------
So select() is returning a set of tuples into a Lua table
named t, and the loop is going to print each element of
......@@ -466,12 +472,11 @@ But you’ve been confined to a space and an index
that Tarantool started with.
Suppose that you want to create your own.
More in the Tarantool manual:
http://tarantool.org/doc/getting_started.html#starting-tarantool-and-making-your-first-database
Request #16 is:
box.schema.create_space("test", {engine="memtx"})!
box.schema.space.create("test", {engine="memtx"})!
--------------------------------------------------
The new space’s name will be "test" and the engine
......@@ -524,7 +529,7 @@ Request #18 is:
for i=65,70,1 do
box.space.test:replace{i, string.char(i)}
end!
-------------------------------------------
-----------------------------------------
Tip: to select the tuples later, use the function
that you created earlier: database_display("test")!
......@@ -538,21 +543,22 @@ Remember, you’re currently "admin" -- administrator.
Now switch to being "guest", a much less powerful user.
Request #19 is:
session.su("guest") -- switch user to "guest"!
box.session.su("guest") -- switch user to "guest"!
box.space.test:replace{100,""} -- try to add a tuple!
-------------------------------
-----------------------------------------------------
The result will be an error message telling you that
you don’t have the privilege to do that any more.
That’s good news. It shows that Tarantool prevents
unauthorized users from working with databases.
But you can say session.su("admin")! to become
But you can say box.session.su("admin")! to become
a powerful user again, because for this tutorial
the "admin" user isn’t protected by a password.
]];
[[
Tutorial -- Screen #20 -- The Bigger Tutorials
Tutorial -- Screen #20 -- The bigger Tutorials
==============================================
You can continue to type in whatever Lua instructions,
......@@ -566,7 +572,7 @@ Insert one million tuples with a Lua stored procedure
http://tarantool.org/doc/book/app/c_lua_tutorial.html#insert-one-million-tuples-with-a-lua-stored-procedure
and
Sum a JSON field for all tuples
http://tarantool.org/doc/master/user_guide.html#lua-tutorial-sum
http://tarantool.org/doc/book/app/c_lua_tutorial.html#sum-a-json-field-for-all-tuples
Request #20 is:
......
test/box/admin.result
+ 2
− 6
View file @ 4c0ac25d
......@@ -17,12 +17,8 @@ test_run:cmd("push filter 'listen: .*' to 'listen: <uri>'")
...
help()
---
- - Help topics:
- Basics
- Administration
- To get help on a topic, type help('topic') (with quotes)
- To get help on a function/object, type help(function) (without quotes)
- To start tutorial, type tutorial()
- - To get help, see the Tarantool manual at http://tarantool.org/doc/
- To start the interactive Tarantool tutorial, type 'tutorial()'
...
cfg_filter(box.cfg)
---
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment