tWaitFor

--{program="tWaitFor",version="1.00",date="2021-04-11"}
---------------------------------------
-- tWaitFor           by Kaikaku
-- 2021-04-16, v1.00   improved blnSilenced
-- 2021-04-11, v0.99   added to rs 'any' and 'change'
--                     and to in 'all' and 'any'
-- 2021-04-10, v0.98   initial
---------------------------------------

---------------------------------------
---- DESCRIPTION ----------------------
---------------------------------------
-- Makes a turtle or computer wait
--   for one of several specified
--   events. Returns the number of the
--   event.accuracy
-- Last argument (if n%3=1) will be
--   used in shell.run(last_argument).
-- Runs only when called with parameters.
--
-- Hints:
-- rs: values need to change to speci-
--     fied value to trigger
-- rn: all specified modem frequencies
--     will be used
-- in: inventory needs to change for
--     slots beeing checked
-- al: if time is at the beginning
--     already within the specified
--     interval, event will trigger
--     after a short delay.


---------------------------------------
---- ASSUMPTIONS ----------------------
---------------------------------------
-- Turtle or computer
-- If there is no modem attached the
--   program will ask for providing/
--   placing one.

-- Improvement ideas:
--   rs: extend to analog
--   in: make checking for changes similar like rs
--   rn: add broadcast


---------------------------------------
---- VARIABLES: template --------------
---------------------------------------
local cVersion  ="v1.00"
local cPrgName  ="tWaitFor"
local blnAskForParameters =true
local blnDebugPrint       =false--true--
local blnSilenced         =false--true--
local blnTurtle
local baseColor=colors.blue


---------------------------------------
---- VARIABLES: specific --------------
---------------------------------------
local modem -- set later in code
local slotFuel=16
local shellDotRun="" -- keeps the parameter for shell.run if there is one
local initalRedstone={front=false, back=false, top=false, bottom=false, right=false, left=false}


---------------------------------------
---- Early UI functions ---------------
---------------------------------------
local function swapColors()
local backColor=term.getBackgroundColor()
local textColor=term.getTextColor()

term.setBackgroundColor(textColor)
term.setTextColor(backColor)
end

local function printUI(strInput)
if strInput==ni then strInput="" end

  if strInput=="header" then
    term.write("—ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒ") swapColors() print("”") swapColors()
  elseif strInput=="line" then
     term.write("ŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒ") swapColors() print("‘") swapColors()
  elseif strInput=="footer" then
    term.write("ŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŽ") print()
  else
    term.write("•")
    strInput=strInput.."                                     "
    term.write(string.sub(strInput,1,37))
    swapColors() print("•") swapColors()
  end
end

local function pprintUI(strInput)
  -- parameterized printUI that can be silinced blnSilenced
  if not blnSilenced then printUI(strInput) end
end

local function coloredTextAt(inputText,outputRow,outputCol,textColor,backColor)
-- writes and colors text to coordinates
local oldRow, oldCol = term.getCursorPos()
local oldTextColor=term.getTextColor()
local oldBackColor=term.getBackgroundColor()
if textColor==nil then textColor=term.getTextColor() end
if backColor==nil then backColor=term.getBackgroundColor() end

  term.setTextColor(textColor)
  term.setBackgroundColor(backColor)
  term.setCursorPos(outputRow,outputCol)
  term.write(inputText)
  term.setCursorPos(oldRow, oldCol)
  term.setTextColor(oldTextColor)
  term.setBackgroundColor(oldBackColor)
end

local function pcoloredTextAt(inputText,outputRow,outputCol,textColor,backColor)
  -- parameterized coloredTextAt that can be silinced blnSilenced
  if not blnSilenced then coloredTextAt(inputText,outputRow,outputCol,textColor,backColor)  end
end

local function ptermwrit(str)
-- parameterized term.write that can be silinced blnSilenced
  if not blnSilenced then term.write(str) end -- TO DO: probably needs attention because of .. / ,
end

local function pprint(str)
-- parameterized print that can be silinced blnSilenced
  if not blnSilenced then print(str) end
end

local function debugPrint(str)
 if blnDebugPrint then print(str) end
end

local function debugSleep(num)
 if num==nil then num=0 end
 if blnDebugPrint then sleep(num) end
end


local function checkFuel()
  local tmp=turtle.getFuelLevel()
  return tmp
end

local function checkTurtle(blnOnlyIdentify)
if blnOnlyIdentify==nil then blnOnlyIdentify=false end
-- turtle?
  local turtleOk, turtleVal = pcall(checkFuel)
  if not turtleOk then
    blnTurtle=false
    if not blnOnlyIdentify then
      if not blnSilenced then term.clear() term.setCursorPos(1,1) end
      printUI("header")
      printUI(""..cPrgName..", "..cVersion..", by Kaikaku")
      printUI("line")
      printUI("This is a turtle program.")
      printUI("  Please, execute it with a turtle!")
      printUI("footer")

      coloredTextAt(cPrgName,2,2,baseColor)
      error()
    end
  else
    blnTurtle=true
  end
end

local function sleepDots(sec, duration)
if sec==nil then sec=10 end
if sec<1 then return end
if duration==nil then duration=1 end -- shorten durtation for more dots

  for i=1,sec-1 do
    sleep(1*duration)
    term.write(".")
  end

  sleep(1*duration)
  print(".")
end

local function getFirstEmptySlot(startAt)
if startAt==nil then startAt=1 end
if startAt>16 or startAt<1 then return nil end

  for i=startAt,16,1 do
    if turtle.getItemCount(i)==0 then return i end
  end
  for i=1,startAt,1 do
    if turtle.getItemCount(i)==0 then return i end
  end
  return nil
end

local function identifyTool(toolSide)
-- returns name of tool at side toolSide
-- returns no_tool if there is none
-- requires at least one empty slot for tool check (throws error)
if toolSide==nil then toolSide="right" end
if toolSide~="right" and toolSide~="r" then toolSide="left" end
local slotNumber = getFirstEmptySlot()
local slotSelected=turtle.getSelectedSlot()
local toolName="no_tool"

  if slotNumber==nil then error("Couldn't find empty slot to check tool on side '"..toolSide.."'!") end
  turtle.select(slotNumber)
  -- step 1: get name
  if toolSide=="right" or toolSide=="r" then
    turtle.equipRight()
  else
    turtle.equipLeft()
  end
  -- step 2: get name
  local data = turtle.getItemDetail()
  if data~=nil then toolName=data.name end
  -- step 3: re-equipget name
  if toolSide=="right" or toolSide=="r" then
    turtle.equipRight()
  else
    turtle.equipLeft()
  end
  turtle.select(slotSelected)
  return toolName
end

local function findModem()
  for _, p in pairs( rs.getSides() ) do
    if peripheral.isPresent(p) and peripheral.getType(p) == "modem" then return true,p end
  end
  return false,nil
end

local function ensureModem()
-- Equips modem from slotFuel either right or left, depending which solt is free.
-- Throws an error if both sides are already taken.
-- Return modem side
local modemExists, modemSide = findModem()

  if not blnTurtle then
    while not modemExists do
      print("No modem found, attach a modem to computer!")
      sleepDots(3)
      modemExists, modemSide = findModem()
    end

  else -- isTurtle
  local slotSelected=turtle.getSelectedSlot()
    while not modemExists do
      turtle.select(slotFuel)
      print("Turtle has no modem, put one wireless modem in slot "..slotFuel.."!")
      sleepDots(3)
      if turtle.getItemCount()== 1 then
        -- check right side
        if identifyTool("right")=="no_tool" then
          turtle.equipRight()
        elseif identifyTool("left")=="no_tool" then
          turtle.equipLeft()
        else
          error("Couldn't find empty tool slot to equip modem! Please, manually remove one tool. E.g., in lua editor with 'turtle.equipLeft()'")
        end
      end
      modemExists, modemSide = findModem()
    end
    turtle.select(slotSelected)
  end
  return modemSide
end


---------------------------------------
---- tArgs ----------------------------
---------------------------------------
local tArgs = {...}
--term.clear() term.setCursorPos(1,1)

-- pre-checks
-- count
if #tArgs==1 or #tArgs%3==2 then
  error(cPrgName.." incorrect number of parameteres. Either 0 (for info screen), a multiple of 3 or a (multiple of 3)+1.")
end

-- extract shell.run
if #tArgs%3==1 then
  -- there is a command for shell.run
  shellDotRun=tArgs[#tArgs]

  -- check for silenced
  if string.sub(shellDotRun,1,8)=="silenced" or string.sub(shellDotRun,1,8)=="silence" then
    blnSilenced=true
    shellDotRun=string.sub(shellDotRun,9)
    -- no need for info print, as it would be silenced anyways :)
  end

  tArgs[#tArgs]=nil --..(tArgs[1] or "").. TO DO
  if shellDotRun~="" then
    debugPrint("Info: Extrated parameter("..(#tArgs+1)..")='"..shellDotRun.."' to be used in shell.run().")
    debugSleep(2)
  end
end

-- header (after silenced check)
if #tArgs~=0 then
  blnAskForParameters=false
  if not blnSilenced then term.clear() term.setCursorPos(1,1) end
  pprintUI("header")
  pprintUI(""..cPrgName..", "..cVersion..", by Kaikaku. Enjoy!")
  pprintUI("line")
  pcoloredTextAt(cPrgName,2,2,baseColor)
  pprint("Starting...")
end

-- correct formats
for i=1,#tArgs,3 do
  pprint("i="..i..":"..tArgs[i])
  if tArgs[i]~="rs" and tArgs[i]~="redstone" and tArgs[i]~="rn" and tArgs[i]~="rednet" and tArgs[i]~="ti" and tArgs[i]~="timer" and tArgs[i]~="al" and tArgs[i]~="alarm" and tArgs[i]~="in" and tArgs[i]~="inventory" then
    error("Invalid paramter("..i..")='"..tArgs[i].."'. Only the following parameters are allowed at each beginning of a 3-tupel: rs, redstone, rn, rednet, ti, timer, al, alarm, in, inventory!")
  end

  -- rs
  if tArgs[i]=="rs" or tArgs[i]=="redstone" then
    -- use abbreviation
    tArgs[i]="rs"
    -- check second
    if tArgs[i+1]~="front" and tArgs[i+1]~="back" and tArgs[i+1]~="top" and tArgs[i+1]~="bottom" and tArgs[i+1]~="left" and tArgs[i+1]~="right" and tArgs[i+1]~="any" then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only the following expressions are allowed as first parameter after rs/redstone: front, back, top, bottom, left, right, any!")
    end
    -- check third
    if tArgs[i+2]~="true" and tArgs[i+2]~="false" and tArgs[i+2]~= "change" then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Only the following expressions are allowed as second parameter after rs/redstone: true, false, change!")
    else
      -- transform into boolean
      if tArgs[i+2]=="true" then tArgs[i+2]=true elseif tArgs[i+2]=="false" then tArgs[i+2]=false end
    end
    -- get current rs status
    initalRedstone['front']=rs.getInput("front")
    initalRedstone['back']=rs.getInput("back")
    initalRedstone['top']=rs.getInput("top")
    initalRedstone['bottom']=rs.getInput("bottom")
    initalRedstone['left']=rs.getInput("left")
    initalRedstone['right']=rs.getInput("right")
  end

  -- ti
  if tArgs[i]=="ti" or tArgs[i]=="timer" then
    -- use abbreviation
    tArgs[i]="ti"
    -- check second
    if tArgs[i+1]~="sec" and tArgs[i+1]~="min" and tArgs[i+1]~="tick" and tArgs[i+1]~="ticks" then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only the following expressions are allowed as first parameter after ti/timer: sec, min, tick!(s)")
    end
    if tArgs[i+1]=="ticks" then tArgs[i+1]="tick" end
    -- check third
    tArgs[i+2]=tonumber(tArgs[i+2])
    if tArgs[i+2]==nil then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Only number expressions are allowed as second parameter after ti/timer!")
    else
      -- transform to sec
      if tArgs[i+1]=="min" then tArgs[i+2]=tArgs[i+2]*60 end
      if tArgs[i+1]=="tick" then tArgs[i+2]=tArgs[i+2]/20 end
    end
    -- start timer
    tArgs[i+1] = os.startTimer(tArgs[i+2])
  end

  -- al
  if tArgs[i]=="al" or tArgs[i]=="alarm" then
    -- use abbreviation
    tArgs[i]="al"
    -- check second
    tArgs[i+1]=tonumber(tArgs[i+1])
    if tArgs[i+1]==nil then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only number expressions are allowed as first parameter after al/alarm!")
    elseif tArgs[i+1]<0 or tArgs[i+1]>=24 then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only numbers [0.0, 24.0) are allowed as first parameter after al/alarm!")
    end
    -- check third
    tArgs[i+2]=tonumber(tArgs[i+2])
    if tArgs[i+2]==nil then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Only number expressions are allowed as second parameter after al/alarm!")
    elseif tArgs[i+2]<0 or tArgs[i+2]>=24 then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Only numbers [0.0, 24.0) are allowed as second parameter after al/alarm!")
    end
    -- prepare alarm(s)
    -- check if already in interval
    if os.time()>=tArgs[i+1] and os.time()<=tArgs[i+2] then
      -- already time for the alarm, set-up immediate alarm
      tArgs[i+2]=os.setAlarm(os.time() + 0.05) -- hm, not sure if 0.05 is the best value
    end
    -- set regular alarm
    tArgs[i+1]=os.setAlarm(tArgs[i+1])
  end

  -- in
  if tArgs[i]=="in" or tArgs[i]=="inventory" then
    -- turtle?
    checkTurtle(true)
    if not blnTurtle then
      error("Invalid paramter("..(i)..")='"..tArgs[i].."'. Only turtles may wait for inventory events!")
    end
    -- use abbreviation
    tArgs[i]="in"
    -- check second
    if tArgs[i+1]~="all" and tArgs[i+1]~="any" then
      tArgs[i+1]=tonumber(tArgs[i+1])
      if tArgs[i+1]==nil then
        error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only slot numbers 1-16 (or 'all'/'any') are allowed as first parameter after in/inventory!")
      end
      tArgs[i+1]=math.floor(tArgs[i+1])
      if tArgs[i+1]<1 or tArgs[i+1]>16 then
        error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only slot numbers 1-16 (or 'all'/'any') are allowed as first parameter after in/inventory!")
      end
    end
    -- check third
    --   string length
    local tmpLen = string.len(tArgs[i+2])
    if tmpLen<2 or tmpLen>3 then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Only 2 or 3 character expressions are allowed as second parameter after in/inventory! (e.g. '>10', '=1', '<20')")
    end
    --    right prefix
    local tmpComp =  string.sub(tArgs[i+2], 1, 1)
    if tmpComp~="<" and tmpComp~="=" and tmpComp~=">" then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. First character of second parameter after in/inventory must be '>', '=' or '<'!")
    end
    --    no impssible
    if tArgs[i+2]=="<0" or tArgs[i+2]==">64" then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. '<0' and '>64' don't make sense for the second parameter after in/inventory!")
    end
    --    numbers
    tArgs[i+2]=string.sub(tArgs[i+2].." ", 2, 3)
    tArgs[i+2]=tonumber(tArgs[i+2])
    if tArgs[i+2]==nil then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Second + third character of second parameter after in/inventory must be digits! (e.g. '>10', '=1', '<20')")
    end
    --    nubers of right interval
    tArgs[i+2]=math.floor(tArgs[i+2])
    if tArgs[i+2]<0 or tArgs[i+2]>64  then
      error("Invalid paramter("..(i+2)..")='"..tArgs[i+2].."'. Second + third character of second parameter after in/inventory must be 0-64!")
    end
    -- remember tmpComp
    tArgs[i]="in"..tmpComp
  end


  -- rn
  if tArgs[i]=="rn" or tArgs[i]=="rednet" then
    -- turtle?
    checkTurtle(true)
    -- modem?
    if modem==nil then modem = peripheral.wrap(ensureModem()) end
    -- use abbreviation
    tArgs[i]="rn"

    -- check second
    tArgs[i+1]=tonumber(tArgs[i+1])
    if tArgs[i+1]==nil then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only numbers (0-65535) can be used as first parameter for channel numbers after rn/rednet!")
    end
    tArgs[i+1]=math.floor(tArgs[i+1])
    if tArgs[i+1]<0 or tArgs[i+1]>65535 then
      error("Invalid paramter("..(i+1)..")='"..tArgs[i+1].."'. Only numbers (0-65535) can be used as first parameter for channel numbers after rn/rednet!")
    end
    modem.open(tArgs[i+1])
  end
end


---------------------------------------
-- basic functions for turtle control -
---------------------------------------

local function waitKey(strText)
  local event, scancode
  term.write(strText)
  event, scancode = os.pullEvent("key")
  print()
end

local function askForInputText(textt)
  local at=""
  -- check prompting texts
  if textt==nil then textt="Enter text:" end

  -- ask for input
  term.write(textt)
  at=read()
  return at
end

local function askForNumber(askText, minValue, maxValue)
-- gets entered data, ensures it's a number and returns it
-- keeps asking if entry is not a number
-- adapts to min and max values
-- allways writes in screen line 13 (last for turtles)
-- calls askForInputText
local blnReask=true
local returnNumber=nil
if minValue==nil then minValur=1 end
if maxValue==nil then maxValue=100 end
if askText==nil then askText="Key in number and press Enter: " end
  while blnReask do
   term.setCursorPos(1,13)
    returnNumber=askForInputText(askText)
    if returnNumber==nil then
      blnReask=true
    else
      returnNumber=tonumber(returnNumber)
      if returnNumber==nil then
        blnReask=true
      else
        returnNumber=math.floor(returnNumber)
        if returnNumber>maxValue then returnNumber=maxValue end
        if returnNumber<minValue then returnNumber=minValue end
        blnReask=false
      end
    end
  end
  return returnNumber
end

local function pressKeyNoSpecials(askText)
-- excludes ctrl / alt / shifts
-- catches windows
-- retruns the key number (if needed at all)
local tmpEvent, tmpKey
if askText==nil then askText="Press key to START! (stop w/ ctrl+t)   " end
  tmpKey=341
  while tmpKey>=340 and tmpKey<=346 do -- ctrls, alts, shifts
    term.write(askText) tmpEvent, tmpKey = os.pullEvent("key")
    if tmpKey==nil then tmpKey=341 end -- win
  end
  return tmpKey
end


------------------------------------------------------------------------------
-- main: description ---------------------------------------------------------
------------------------------------------------------------------------------

if blnAskForParameters then
term.clear() term.setCursorPos(1,1)
local iPage=0
local iPageMax=11
local event, key, isHeld
local blnLoop=true

term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("This program makes a turtle or ")
printUI("  computer wait for a specified")
printUI("  event.")
printUI("You can specify as many events as you")
printUI("  like, the first that occurs ends")
printUI("  the program and the event number is")
printUI("  returned. I.e. if the second event")
printUI("  triggers '2' is returned.")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")



term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("The following events can be used:")
printUI("  ")
printUI("* rs/redstone: redstone changes")
printUI("* rn/rednet: rednet messages")
printUI("* ti/timer: timer events")
printUI("* al/alarm: alarm events")
printUI("* in/inventory: inventory changes")
printUI("  ")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("rs",4,6,baseColor)
coloredTextAt("rn",4,7,baseColor)
coloredTextAt("ti",4,8,baseColor)
coloredTextAt("al",4,9,baseColor)
coloredTextAt("in",4,10,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Each event is specified with exactly ")
printUI("  3 parameters. That is the number of")
printUI("  paramteres must be a multiple of 3.")
printUI("Option: You may provide one more")
printUI("  parameter, that will be used after ")
printUI("  the trigger, in an shell.run()")
printUI("  command. I.e. you can start a")
printUI("  program waiting for an event.")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("3 parameters",4,5,baseColor)
coloredTextAt("shell.run()",23,9,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")



term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Option: If you want to use the ")
printUI("  program within another program, you")
printUI("  might want to suppress the messages")
printUI("  showing up.")
printUI('To do so add "silenced" directly ')
printUI("  before the program name to be run ")
printUI("  in shell.run() respectively add it")
printUI('  instead, e.g. "silenceddance".')
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("silenced",16,8,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")

term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Syntax for redstone changes:")
printUI("  rs/redstone side true/false/change")
printUI("  side: front, back, left, right,")
printUI("        top, bottom, any")
printUI("The event will trigger if the red-")
printUI("  stone signal at this side changes")
printUI("  to the specified boolean value.")
printUI("Example: rs back true")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("redstone",13,4,colors.white,baseColor)
coloredTextAt("rs/redstone side true/false/change",4,5,baseColor)
coloredTextAt("rs back true",11,11,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Syntax for rednet messages:")
printUI("  rn/rednet channel message")
printUI("  channel: 0-65535")
printUI('  message: "use quotes for text"')
printUI("The event will trigger if the message")
printUI("  is received on the channel.")
printUI("  Requires a modem.")
printUI('Example: rn 1 "Hello World!"')
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("rednet",13,4,colors.white,baseColor)
coloredTextAt("rn/rednet channel message",4,5,baseColor)
coloredTextAt('rn 1 "Hello World!"',11,11,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Syntax for timer events:")
printUI("  ti/timer unit number")
printUI("  unit: sec/min/tick(s)")
printUI("  number: waits so long")
printUI("The event will trigger after the ")
printUI("  spefied time expired.")
printUI("  20 ticks = 1 sec")
printUI("Example: ti min 2.5")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("timer",13,4,colors.white,baseColor)
coloredTextAt("ti/timer unit number",4,5,baseColor)
coloredTextAt("ti min 2.5",11,11,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Syntax for alarm events:")
printUI("  al/alarm start end")
printUI("start: MC time the event triggers,")
printUI("  0.00 - 23.99 (with 12.00=noon)")
printUI("end: checks at the beginning, if ")
printUI("  time>start and time<end then it")
printUI("  will trigger after a short delay.")
printUI("Example: al 12.0 12.0")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("alarm",13,4,colors.white,baseColor)
coloredTextAt("al/alarm start end",4,5,baseColor)
coloredTextAt("al 12.0 12.0",11,11,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Syntax for inventory events:")
printUI("  in/inventory slot >=<number")
printUI("slot: turtle(!) slot 1-16 or all/any")
printUI(">=<number: Is a compound parameter.")
printUI("number specifies the item count 0-64")
printUI("and the prefix > or = or < the con-")
printUI("dition (triggers with first update).")
printUI("Example: in 1 >10")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("inventory",13,4,colors.white,baseColor)
coloredTextAt("in/inventory slot >=<number",4,5,baseColor)
coloredTextAt("in 1 >10",11,11,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Example 1:")
printUI(" ")
printUI("tWaitFor rs left false ti min 10")
printUI(" ")
printUI("Triggers either if redstone signal")
printUI("on left side changes(!) from on to ")
printUI("off or after 10 minutes.")
printUI(" ")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("Example 1:",2,4,colors.white,baseColor)
coloredTextAt("tWaitFor rs left false ti min 10",2,6,baseColor)

pressKeyNoSpecials("Press key for next. (stop w/ ctrl+t)   ")


term.clear() term.setCursorPos(1,1) iPage=iPage+1
printUI("header")
printUI(""..cPrgName..", "..cVersion..", by Kaikaku ("..iPage.."/"..iPageMax..")")
printUI("line")
--       1234567890123456789012345678901234567
printUI("Example 2:")
printUI(" ")
printUI('tWaitFor rn 4 "let us go" "go fd 10"')
printUI(" ")
printUI('Triggers with message "let us go" on ')
printUI('channel 4 and executes the program   ')
printUI('"go fd 10", i.e. the turtle moves ')
printUI("forward 10 blocks.")
printUI("footer")

coloredTextAt(cPrgName,2,2,baseColor)
coloredTextAt("Example 2:",2,4,colors.white,baseColor)
coloredTextAt('tWaitFor rn 4 "let us go" "go fd 10"',2,6,baseColor)

pressKeyNoSpecials("Press key to exit.                     ")

return
end


---------------------------------------
-- additional functions               -
---------------------------------------

local function checkRedstoneInput(side, compareTo)
if side==nil then side="front" end
if compareTo==nil then side="change" end
  -- compares current input to initalRedstone
  if side~="any" then
    -- one side
    if rs.getInput(side)~=initalRedstone[side] then
      -- change happened
      pprint("Right side has changed")
      if compareTo=="change" then
        return true
      end
      if rs.getInput(side)==compareTo then
        pprint("... and to the right value!")
        return true
      else
        -- adapt initalRedstone
        initalRedstone[side]=rs.getInput(side)
      end
    else
      pprint("Other side has changed")
    end
  else
    -- any side
    if checkRedstoneInput("front", compareTo)  then return true end
    if checkRedstoneInput("back", compareTo)   then return true end
    if checkRedstoneInput("left", compareTo)   then return true end
    if checkRedstoneInput("right", compareTo)  then return true end
    if checkRedstoneInput("top", compareTo)    then return true end
    if checkRedstoneInput("bottom", compareTo) then return true end
  end
  return false
end

local function checkInventroyCount(mode, slot, number)
if mode==nil then mode="in=" end
if slot==nil then slot=0 end
if number==nil then number=0 end
local isOkay=true

  if slot=="all" then
    -- all
    for i=1,16 do
print(i)
      isOkay = isOkay and checkInventroyCount(mode, i, number)
      if not isOkay then return false end
    end
    return true

  elseif slot=="any" then
    -- any
    for i=1,16 do
      if checkInventroyCount(mode, i, number)  then return true end
    end
  else
    -- slot 1-16
    if mode=="in<" then
      if turtle.getItemCount(slot)<number  then return true end
    elseif mode=="in>" then
      if turtle.getItemCount(slot)>number  then return true end
    else -- "in="
      if turtle.getItemCount(slot)==number then return true end
    end
  end

  return false
end

------------------------------------------------------------------------------
-- main: program -------------------------------------------------------------
------------------------------------------------------------------------------
if not blnSilenced then term.clear() term.setCursorPos(1,1) end
---- step 1: waiting for event ----
pprint("Waiting for event...")

local returnResult=""

blnLoop=true
while blnLoop do

  local event, param1, param2, param3, param4, param5 = os.pullEvent()

  -- ignore a bunch of events
  if event~="key" and event~="key_up" and event~="char" and event~="mouse_up" and event~="mouse_click" then

  -- post processing rednet.send
  if param4~=nil then
    if param4.message~=nil then param4=param4.message end
  end

    -- print event data
    if blnDebugPrint then
      pprint(" e="..event)--(tArgs[1] or "")
      if param1~=nil then pprint(" p1="..param1) end
      if param2~=nil then pprint(" p2="..param2) end
      if param3~=nil then pprint(" p3="..param3) end
      if param4~=nil then pprint(" p4="..param4) end
      if param5~=nil then pprint(" p5="..param5) end
    end

    -- rs
    if event == "redstone" then
      -- got a redstone event
      pprint( "Redstone event..." )
      for i=1,#tArgs,3 do
        if tArgs[i]=="rs" then
          --pprint("... i("..i..") rs |"..tArgs[i+1].."|"..tArgs[i+2])
          pprint("... i("..i..") rs | "..tostring(tArgs[i+1]).." | "..tostring(tArgs[i+2]))
          if checkRedstoneInput(tArgs[i+1],tArgs[i+2]) then pprint("Match!") blnLoop=false returnResult=(i+2)/3 break end
        end
      end
    end

    -- ti
    if event == "timer" then
      -- got a timer event
      pprint( "Timer event..." )
      for i=1,#tArgs,3 do
        if tArgs[i]=="ti" then
          pprint("... i("..i..") ti | sec | "..tostring(tArgs[i+2]))
          if param1==tArgs[i+1] then pprint("Match!") blnLoop=false returnResult=(i+2)/3 break end
        end
      end
    end

    -- al
    if event == "alarm" then
      -- got an alarm event
      pprint( "Alarm event..." )
      for i=1,#tArgs,3 do
        if tArgs[i]=="al" then
          pprint("... i("..i..") al | triggered @ "..os.time())
          if param1==tArgs[i+1] then pprint("Match!")      blnLoop=false returnResult=(i+2)/3 break end
          if param1==tArgs[i+2] then pprint("Late Match!") blnLoop=false returnResult=(i+2)/3 break end
        end
      end
    end

    -- in
    if event == "turtle_inventory" then
      -- got an inventory event
      pprint( "Inventory event..." )
      for i=1,#tArgs,3 do
        if tArgs[i]=="in=" or tArgs[i]=="in>" or tArgs[i]=="in<" then
          pprint("... i("..i..") in | "..tostring(tArgs[i+1]).." | "..string.sub(tArgs[i],3,3)..tostring(tArgs[i+2]))
          if checkInventroyCount(tArgs[i], tArgs[i+1], tArgs[i+2]) then pprint("Match!") blnLoop=false returnResult=(i+2)/3 break end
        end
      end
    end

    -- rn
    if event == "modem_message" then --or event == "rednet_message"then
      -- got an alarm event
      pprint( "Rednet event..." )
      for i=1,#tArgs,3 do
        if tArgs[i]=="rn" then
          pprint("... i("..i..") rn | "..tostring(tArgs[i+1]).." | "..tostring(tArgs[i+2]))
          if param2==tArgs[i+1] and param4==tArgs[i+2] then pprint("Match!") blnLoop=false returnResult=(i+2)/3 break end
        end
      end
    end
  end
end


---- step 2: finishing stuff / report ----
pprint("Triggered event = "..returnResult)
pprint("That was eventful !")
pprintUI("header")
pprintUI("Check out YouTube for more videos")
pprintUI("and turtle programs by Kaikaku :)")
pprintUI("footer")
local tmpX, tmpY = term.getCursorPos() pcoloredTextAt("Kaikaku",9+16,tmpY-2,baseColor) -- <<-- put line in template
if shellDotRun~="" then
  pprint("Executing: shell.run("..shellDotRun..")")
  debugSleep(2)
  shell.run(shellDotRun)
end

return returnResult