Lua Task 1 - Introduction to Lua in Wikipedia
editLua is a lightweight programming language that is particularly suited for embedding within other software. The software used by Wikipedia, called MediaWiki, has an extension that provides a version of Lua that can be used within Wikipedia pages. The extension is called Scribunto.
1. Create a Wikipedia account – see: https://en.wikipedia.org/wiki/Wikipedia:Why_create_an_account%3F Adding an email address allows you to reset your password if you forget it.
2. Use the link at the top right of your page that has your username to create your user page. Add some text, noting that you’re taking part in GCI, but don’t add personal information. Preview your edit and save it.
3. Use the link at the top right of your page to create your sandbox. Type some text, preview it and save it. Remember that what you type can potentially be seen by anybody, so be sensisble!
4. Read about Scribunto, the Lua implementation embedded in WikiMedia software: https://en.wikipedia.org/wiki/Wikipedia:Lua
5. Create an empty sandbox module for yourself as a subfolder of https://en.wikipedia.org/wiki/Module:Sandbox For example, if your user name is "Joe Bloggs", then create your module at https://en.wikipedia.org/wiki/Module:Sandbox/Joe_Bloggs Note that any spaces need to be converted to underscores, "_". This is called urlencoding.
In you sandbox add a line of text starting with two hyphens: -- After the two hyphens, type your username followed by "Google Code-in 2017, Introduction to Lua in Wikipedia" Text beginning with two hyphens is used in Lua to designate a comment.
Lua Task 2 - Using Lua in Wikipedia
editPrerequisite: Lua Task 1 - Introduction to Lua in Wikipedia
A Wikipedia page can call a Lua module to do calculations, process text, format citations, fetch information from Wikidata, and many other jobs where a programming language is needed to get a result.
1. A Lua module is used inside a Wikipedia page by using a call something like Horses and thunderstorm1.jpg Type or copy that line as a new line at the end of your sandbox (not your sandbox module) and save it. You should see the filename of a JPG image. The line makes use of a module called Module:RexxS. Modules can contain many functions and the line you have entered calls a function in that module called "carousel".
2. Modify that line to read
and save it. This uses the standard Wikipedia image syntax to display the image. You can read a lot more about image syntax at https://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax if you are interested.
3. Look at https://en.wikipedia.org/wiki/Module:RexxS and examine the code. See if you can work out how the function picks a filename. You may find the documentation at http://www.lua.org/manual/5.3/ helps you to learn how Lua works. In your sandbox, on a new line, write down the name of the list (a Lua table) that stores the filenames.
Lua Task 3 - Creating your own Lua module
editPrerequisite: Lua Task 2 - Using Lua in Wikipedia
You can write your own Lua functions using your sandbox module to try out code. You can then use your sandbox to call a function from your module and see how well it works.
1. Read the "Introduction - Getting started" and "Introduction - Module structure" sections at https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual Make sure you understand that the module begins by defining an empty table, then defines functions (adding them to the table), and finally returns the table.
2. Copy the following three questions into your sandbox (not your module sandbox): Which letter is conventionally used in Scribunto modules to hold the table of functions? What keyword marks the start of a function definition? What keyword marks the end of a function definition?
3. Write your answers to the three questions in your sandbox.
4. In your module sandbox you should just have a comment (-- Google Code-in 2017, Introduction to Lua in Wikipedia). On a new line write another similar comment with the name of this task. Save the module.
5. Below that comment, copy all of the code needed to produce the "hello" function from the example at https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Getting_started Include the inital line beginning "local ...", and the final line beginning "return ...". Save the module.
6. Work out want you need to write in your sandbox in order to call the "hello" function from your module sandbox. Write that in your sandbox and test it by previewing the edit. When you are satisfied that you have no errors, save the sandbox.
Lua Task 4 - Passing information to your Lua module
editPrerequisite: Lua Task 3 - Creating your own Lua module
Lots of uses of modules in Wikipedia require some information from the page where they are placed. We call information passed to a function a "parameter".
1 Examine https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/SayHello - you should see a function called 'Hi'. Copy it into your module sandbox (you already have the first and last lines, so you just need to copy the function, but make sure you copy it before the last line return p).
2 Edit your sandbox to add this line at the end:
Hello from Lua to my friend Andy.
Save it and observe the result. The word 'Andy' is passed as the value of the parameter called 'name'.
3. Add another line to your sandbox that calls the function 'Hi' from your module sandbox instead. Save it.
4. Edit that line to change the name from Andy to your name. Save it.
5. Change your module sandbox so that the first line inside the function 'Hi' reads strName = frame.args.name or "Jimbo" Save it.
6. Add another line to your sandbox that is a copy of the previous line but without |name=Andy. Save it. We use the 'or' operator to supply a default that is used if no parameter is given.
Lua Task 5 - Calculations
editPrerequisite: Lua Task 4 - Passing information to your Lua module. This task requires some independent learning.
In a Lua function, we can do the usual programming jobs, such as calculations, text processing, testing and repeating blocks of code. You'll need to read [[ https://www.lua.org/manual/5.3/manual.html | The Reference Manual]] if you are uncertain about anything.
1 In your module sandbox, create a new function called "temperature". In the call, we will pass a parameter named "celsius" and store it inside the function as a variable named "cel". We will then convert it to fahrenheit and store it in a variable named "fah". Finally, we will return both values along with some text.
Use the line ``` cel = frame.args.celsius ``` to get the parameter "celsius" and store it in the variable "cel".
2 To convert, we multiply a value in Celsius by 9, then divide it by 5, and add 32. Write a line starting ``` fah = ``` to do that conversion. You'll need the multiplication (*), division (/), and addition (+) operators.
3 Write a line of code that returns something like `"15 degrees Celsius is 59 degrees Fahrenheit."` when the function is passed 15 as the `|celsius=` parameter. Save your module sandbox. You'll need the concatenation (..) operator.
4 In your sandbox, write a line that calls your module sandbox function "temperature", passing 5 as the parameter, Write another line that calls the function with 25 as the parameter. Save your sandbox. Fix any errors that occur.
Lua Task 6 - Tests
editPrerequisite: Lua Task 5 - Calculations. This task requires independent learning and is more difficult.
Note that a Scribunto function always returns a //string // (i.e. text) to the Wikipedia page where it is invoked. Lua variables are //dynamically-typed//. That means that variables do not have a type, only values have a type. Lua will generally do its best to convert from one type to another as needed. For example, you can concatenate text with numbers without having to explicitly convert the number to a string first.
Lua uses the `if <test> then <do-if-true> else <do-if-false> end` structure to pick one of two outcomes depending on whether the test turns out true or false.
1 In your module sandbox, amend the function "temperature" to supply 0 as the default if no parameter is supplied. Save it.
2 Write a line in your sandbox to test that. Save it.
3 Make changes to the function "temperature" to store the text that you are returning in a variable called "msg". Then `return msg` as the last line before the `end` of the function. Save it and check in your sandbox that it is still working.
4 Change function "temperature" to test whether the value of "cel" is greater than 9. If it is greater, then add "` It is warm.`" to "msg", otherwise add "` It is cold.`" - you'll need the concatenation operator (..) and a construction like `msg = msg .. " blah blah"`.
5 Test your function in your sandbox with different values of the parameter to make sure that the test works as expected.
Lua Task 7 - Repeating code
editPrerequisite: Lua Task 6 - Tests. This task requires independent learning and is more difficult.
Lua has several //[[ https://www.lua.org/manual/5.3/manual.html#3.3.4 | control structures ]]//: `if`, `while`, `repeat`, `for ` - this task will focus on the simple numerical [[ https://www.lua.org/manual/5.3/manual.html#3.3.5 | `for` loop]].
1 Examine https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/GCI07
The line
```
local num = tonumber(frame.args.num) or 2
```
uses a built-in Lua function called '"tonumber" which explicitly tries to convert its argument to a number. If it fails, then 2 is used instead as the value for "num".
Read through the function line-by-line and work out what each line does. The
is a html tag that creates a line-break, i.e. the display continues on the next line.
2 Examine https://en.wikipedia.org/wiki/User:RexxS/sandboxGCI#Lua_Task_7 This contains "test cases" for the function, which test how it behaves when given different possible inputs: nothing, blank, text, positive number, negative number.
3 Copy the function "times" into your module sandbox. Save it.
4 Edit "times" in your module sandbox so that the heading reads something like "`2 times table`". Save it. Test it in your sandbox. (Do that for each following instruction).
5 Edit "times" so that it displays "`2 times 1 equals 2`", etc.
6 Edit "times" so that it displays each table up to 12 times instead of 10 times.
7 Leave a comment **here** linking to your sandbox.
Lua Task 8 - Lua Tables
editPrerequisite: Lua Task 7 - Repeating code. This task requires independent learning and is more difficult.
Lua has one structure - the table - that is used to store arrays, lists, or sets of values. The values may be of any type.
A simple table is demonstrated in https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/GCI08 and it is tested in https://en.wikipedia.org/wiki/User:RexxS/sandboxGCI#Lua_Task_8
1 Make a copy of the function "mum" in your module sandbox. Save it.
2 Make a new section in your sandbox:
== Task 8 ==
and create a test for your "mum" function. Save it.
3 Amend your code so that it will display "`Hello Dad`" instead. Check it in your sandbox. (Do the check for each of the following instructions.)
Note that `family[i]` (where `i` is a variable containing a number) will refer to the ith member of the "family" table. Arrays in Lua start at 1 by default.
4 Amend your code so that it uses a numeric `for` loop to go from 1 to 5 to display "Hello " followed by each member of the "family" table.
5 Amend your code so you add two more names to the "family" table. These won't automatically display.
You can find the size of a simple table like "family" by using `#family` which gives the number of members of the table.
6 Amend your code so that it always displays all of the "family" members.
7 Amend your code so you add one more name to the "family" table. Check that it displays.
8 Leave a comment **here** linking to your sandbox.
Lua Task 9 - MediaWiki Libraries
editPrerequisite: Lua Task 8 - Lua Tables. This task requires research and independent learning. It may not be suitable for beginners to programming.
Read the Module documentation at [[ https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/GCI09 | Module:Sandbox/RexxS/GCI09 ]] and check the pages linked.
1 Copy the function 'langnames' from https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/GCI09 to your module sandbox. Read https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#mw.language.fetchLanguageNames to work out what it does. The for loop demonstrates an example of how we could extract all of the data in a table into a string that we can return to the wiki-page.
2 Write a call in a new section of your sandbox called `==Task 9==` that calls 'langnames' from **your module sandbox**.
I want a function called 'pageinfo' that takes a title as a parameter and returns some information about the corresponding Wikipedia page. Here are some examples of what I want it to display: Color exists and is not a redirect Colour exists and is a redirect Colr does not exist and is not a redirect
3 In your module sandbox, write a function that uses mw.title.new from the manual to create a title object that we can use to test whether the given title exists and whether it is a redirect. If you need a start, copy the code from https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/GCI09a and improve on that.
4 In your sandbox write 6 test cases to show your module works. Link it from here.
[Lua task #10] Update code of the "Reign" template on English Wikipedia
editPrerequisite: To work on this task, you MUST have some knowledge of Lua programming already (or another language plus completing the previous basic Lua tasks here in Google Code-in).
On Wikipedia, editors generally use templates to perform complex tasks, not least of which is ensuring that items are displayed in a consistent manner across Wikipedia.
1 Read the documentation for [Template:Reign](https://en.wikipedia.org/wiki/Template:Reign), which is used to provide a consistent display of the reigns of kings, emperors, etc.
2 Read the discussion at [Probably-simple conversion](https://en.wikipedia.org/wiki/Wikipedia_talk:Lua #Probably-simple_conversion), particularly noting the numerous test cases.
3 Create a new sandbox in your user space and collect as many of the test cases as you can find on that page.
If you understand Wikipedia template coding, examine the source of `Template:Reign` and work out an algorithm to duplicate its functionality. Otherwise, try to work out an algorithm from the task description.
4 Create a new Module sandbox and write a function that takes the same parameters as `Template:Reign`, and produces the correct output for each of the test cases.
5 In your sandbox, write calls to your module for each of the test cases that demonstrate the output for them.
[Lua task #11] Create a general date-handling function
editPrerequisite: To work on this task, you MUST have knowledge of Lua programming already, or another language plus Lua tasks 1-9 here in Google Code-in. You will need to learn about [[ https://www.lua.org/manual/5.3/manual.html#6.4.1 | Lua patterns ]] (similar to regular expressions).
Wikipedia sometimes get dates written in unusual styles. There are four generally useful styles that we want to standardise on:
- dmy format, e.g. 22 December 2017
- mdy format, e.g. December 22, 2017
- iso format, e.g. 2017-12-22
- y format, e.g. 2017
They may be used in different contexts in Wikipedia, so a general date-handling function should accept a parameter to specify what output is required. e.g. |dateformat=dmy. Those are the four basic formats that we want the function to output, as selected by dateformat.
The input should be a piece of text that may contain a date. There are some examples at [[ https://en.wikipedia.org/wiki/User:RexxS/DateDataTest |User:RexxS/DateDataTest]].
You can add to those that dmy dates and mdy dates may have a suffix, which may be any of "AD", "BC", "CE", or "BCE". You'll need to have another input parameter that specifies either the AD/BC or CE/BCE styles for output.
1 Create a sandbox section that collects as many different types of test cases as you can think of.
2 Create a function that will accept arbitrary text and extract from it a likely date, then output it in the selected format.
3 Test your function with all of your cases. Give a link here.
[Lua task #12] Find the author
editPrerequisite: To work on this task, you MUST have knowledge of Lua programming already, or another language plus Lua tasks #01 to #09 here in Google Code-in. You will need to do considerable research and creation of test cases before starting to do the programming.
Wikipedia uses citations extensively to verify the content. A citation may have an author's name as a single piece of text, e.g. "Joe Orton" or sometimes "J Orton". Optionally, it may refine it into two pieces of information: a last name (often a family name) such as "Orton" and a given name such as "Joe". This is called increasing the data granularity.
The task of transforming from a single name to last name and given name can have complications that are difficult to encode algorithmically, so we might create a look-up table of exceptions to the general rule that the last name is the last word in the author's name.
1 Find as many examples as you can of authors whose names are not simply "Firstname(s) Lastname" and make a list of them in a new sandbox or section. You may need to search further to work out which have complex last names.
You can consult lists like https://www.theguardian.com/books/list/authorsaz for examples, and you can look through Wikipedia articles' citations for more.
2 Mark them up in your sandbox in a way that you can tell which part is first name and which is last name.
3 Write a new sandbox module that takes a single name and returns two parts: the first names and the last name. Give links here.
[Lua task #13] Documentation
editPrerequisite: one of Lua tasks 10, 11, or 12.
Documentation is a much under-appreciated skill for a programmer. Creating good documentation has multiple benefits both for the end-user and for you and other programmers. When you return to your code months later to make updates, can you quickly find the right section of your code? Make your code readable and easy to understand by using relevant variable and function names and by adding brief annotations. Understanding where annotations are helpful, and where they are mere clutter is a difficult skill to master. When you have assembled a suite of test cases to ensure your code is working as intended, make the cases available to others by linking to them from the main program repository. Finally, write comprehensive instructions for the end-user, who may not have a technical background, give extensive examples and point out any limitations or pitfalls with your code.
Examine https://en.wikipedia.org/wiki/Module:Sandbox/RexxS - it automatically displays the documentation at https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/doc
Note the use of sections, heading levels, and bulleted lists. Each of the functions is described and examples given.
1 Working on task 10, 11 or 12, create a doc subpage for your module. On that page, describe as simply and clearly as possible what your module does. Link to your test-cases, and give clear examples of normal use as well as unusual examples, and describe any potential problems with your code.